##// END OF EJS Templates
Refactor autogen config
klonuo -
Show More
@@ -1,160 +1,159 b''
1 # Makefile for Sphinx documentation
1 # Makefile for Sphinx documentation
2 #
2 #
3
3
4 # You can set these variables from the command line.
4 # You can set these variables from the command line.
5 SPHINXOPTS =
5 SPHINXOPTS =
6 SPHINXBUILD = sphinx-build
6 SPHINXBUILD = sphinx-build
7 PAPER =
7 PAPER =
8 SRCDIR = source
8 SRCDIR = source
9 BUILDDIR = build
9 BUILDDIR = build
10 PYTHON = python
10 PYTHON = python
11
11
12 # Internal variables.
12 # Internal variables.
13 PAPEROPT_a4 = -D latex_paper_size=a4
13 PAPEROPT_a4 = -D latex_paper_size=a4
14 PAPEROPT_letter = -D latex_paper_size=letter
14 PAPEROPT_letter = -D latex_paper_size=letter
15 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
15 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
16
16
17 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
17 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
18
18
19 default: html
19 default: html
20
20
21 help:
21 help:
22 @echo "Please use \`make <target>' where <target> is one of"
22 @echo "Please use \`make <target>' where <target> is one of"
23 @echo " html standalone HTML files"
23 @echo " html standalone HTML files"
24 @echo " html_noapi same as above, without the time consuming API docs"
24 @echo " html_noapi same as above, without the time consuming API docs"
25 @echo " pickle pickle files (usable by e.g. sphinx-web)"
25 @echo " pickle pickle files (usable by e.g. sphinx-web)"
26 @echo " htmlhelp HTML files and a HTML help project"
26 @echo " htmlhelp HTML files and a HTML help project"
27 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
27 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
28 @echo " texinfo Texinfo files"
28 @echo " texinfo Texinfo files"
29 @echo " info Texinfo files and run them through makeinfo"
29 @echo " info Texinfo files and run them through makeinfo"
30 @echo " changes an overview over all changed/added/deprecated items"
30 @echo " changes an overview over all changed/added/deprecated items"
31 @echo " linkcheck check all external links for integrity (takes a long time)"
31 @echo " linkcheck check all external links for integrity (takes a long time)"
32 @echo " gh-pages clone IPython docs in ./gh-pages/ , build doc, autocommit"
32 @echo " gh-pages clone IPython docs in ./gh-pages/ , build doc, autocommit"
33 @echo
33 @echo
34 @echo "Compound utility targets:"
34 @echo "Compound utility targets:"
35 @echo "pdf latex and then runs the PDF generation"
35 @echo "pdf latex and then runs the PDF generation"
36 @echo "all html and pdf"
36 @echo "all html and pdf"
37 @echo "dist all, and then puts the results in dist/"
37 @echo "dist all, and then puts the results in dist/"
38
38
39 clean_api:
39 clean_api:
40 -rm -rf $(SRCDIR)/api/generated
40 -rm -rf $(SRCDIR)/api/generated
41
41
42 clean: clean_api
42 clean: clean_api
43 -rm -rf build/* dist/*
43 -rm -rf build/* dist/*
44 -cd $(SRCDIR)/config/options; test -f generated && cat generated | xargs rm -f
44 -rm -f $(SRCDIR)/config/options/config-generated.txt
45 -rm -rf $(SRCDIR)/config/options/generated
46 -rm -f $(SRCDIR)/interactive/magics-generated.txt
45 -rm -f $(SRCDIR)/interactive/magics-generated.txt
47
46
48 pdf: latex
47 pdf: latex
49 cd build/latex && make all-pdf
48 cd build/latex && make all-pdf
50
49
51 all: html pdf
50 all: html pdf
52
51
53 # For final distribution, only build HTML (our pdf is now so large as to be
52 # For final distribution, only build HTML (our pdf is now so large as to be
54 # unusable, takes forever to build and just bloats the downloads). We leave
53 # unusable, takes forever to build and just bloats the downloads). We leave
55 # them hardlinked at the top-level so users find them easily, though the
54 # them hardlinked at the top-level so users find them easily, though the
56 # original build/html dir is left in-place (useful to reload builds while
55 # original build/html dir is left in-place (useful to reload builds while
57 # testing).
56 # testing).
58 dist: html
57 dist: html
59 rm -rf html
58 rm -rf html
60 cp -al build/html .
59 cp -al build/html .
61 @echo "Build finished. Final docs are in html/"
60 @echo "Build finished. Final docs are in html/"
62
61
63 html: api autoconfig automagic
62 html: api autoconfig automagic
64 html_noapi: clean_api autoconfig automagic
63 html_noapi: clean_api autoconfig automagic
65
64
66 html html_noapi:
65 html html_noapi:
67 mkdir -p build/html build/doctrees
66 mkdir -p build/html build/doctrees
68 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
67 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
69 @echo
68 @echo
70 @echo "Build finished. The HTML pages are in build/html."
69 @echo "Build finished. The HTML pages are in build/html."
71
70
72 automagic: source/interactive/magics-generated.txt
71 automagic: source/interactive/magics-generated.txt
73
72
74 source/interactive/magics-generated.txt: autogen_magics.py
73 source/interactive/magics-generated.txt: autogen_magics.py
75 $(PYTHON) autogen_magics.py
74 $(PYTHON) autogen_magics.py
76 @echo "Created docs for line & cell magics"
75 @echo "Created docs for line & cell magics"
77
76
78 autoconfig: source/config/options/generated
77 autoconfig: source/config/options/config-generated.txt
79
78
80 source/config/options/generated:
79 source/config/options/generated:
81 $(PYTHON) autogen_config.py
80 $(PYTHON) autogen_config.py
82 @echo "Created docs for config options"
81 @echo "Created docs for config options"
83
82
84 api: source/api/generated/gen.txt
83 api: source/api/generated/gen.txt
85
84
86 source/api/generated/gen.txt:
85 source/api/generated/gen.txt:
87 $(PYTHON) autogen_api.py
86 $(PYTHON) autogen_api.py
88 @echo "Build API docs finished."
87 @echo "Build API docs finished."
89
88
90 pickle:
89 pickle:
91 mkdir -p build/pickle build/doctrees
90 mkdir -p build/pickle build/doctrees
92 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
91 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
93 @echo
92 @echo
94 @echo "Build finished; now you can process the pickle files or run"
93 @echo "Build finished; now you can process the pickle files or run"
95 @echo " sphinx-web build/pickle"
94 @echo " sphinx-web build/pickle"
96 @echo "to start the sphinx-web server."
95 @echo "to start the sphinx-web server."
97
96
98 web: pickle
97 web: pickle
99
98
100 htmlhelp:
99 htmlhelp:
101 mkdir -p build/htmlhelp build/doctrees
100 mkdir -p build/htmlhelp build/doctrees
102 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
101 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
103 @echo
102 @echo
104 @echo "Build finished; now you can run HTML Help Workshop with the" \
103 @echo "Build finished; now you can run HTML Help Workshop with the" \
105 ".hhp project file in build/htmlhelp."
104 ".hhp project file in build/htmlhelp."
106
105
107 qthelp:
106 qthelp:
108 mkdir -p build/qthelp
107 mkdir -p build/qthelp
109 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
108 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
110 @echo
109 @echo
111 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
110 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
112 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
111 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
113 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
112 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
114 @echo "To view the help file:"
113 @echo "To view the help file:"
115 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
114 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
116
115
117 latex: api autoconfig
116 latex: api autoconfig
118 mkdir -p build/latex build/doctrees
117 mkdir -p build/latex build/doctrees
119 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
118 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
120 @echo
119 @echo
121 @echo "Build finished; the LaTeX files are in build/latex."
120 @echo "Build finished; the LaTeX files are in build/latex."
122 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
121 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
123 "run these through (pdf)latex."
122 "run these through (pdf)latex."
124
123
125 changes:
124 changes:
126 mkdir -p build/changes build/doctrees
125 mkdir -p build/changes build/doctrees
127 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
126 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
128 @echo
127 @echo
129 @echo "The overview file is in build/changes."
128 @echo "The overview file is in build/changes."
130
129
131 linkcheck:
130 linkcheck:
132 mkdir -p build/linkcheck build/doctrees
131 mkdir -p build/linkcheck build/doctrees
133 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
132 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
134 @echo
133 @echo
135 @echo "Link check complete; look for any errors in the above output " \
134 @echo "Link check complete; look for any errors in the above output " \
136 "or in build/linkcheck/output.rst."
135 "or in build/linkcheck/output.rst."
137
136
138 nightly: dist
137 nightly: dist
139 rsync -avH --delete dist/ ipython:www/doc/nightly
138 rsync -avH --delete dist/ ipython:www/doc/nightly
140
139
141 gh-pages: clean html
140 gh-pages: clean html
142 # if VERSION is unspecified, it will be dev
141 # if VERSION is unspecified, it will be dev
143 # For releases, VERSION should be just the major version,
142 # For releases, VERSION should be just the major version,
144 # e.g. VERSION=2 make gh-pages
143 # e.g. VERSION=2 make gh-pages
145 $(PYTHON) gh-pages.py $(VERSION)
144 $(PYTHON) gh-pages.py $(VERSION)
146
145
147 texinfo:
146 texinfo:
148 mkdir -p $(BUILDDIR)/texinfo
147 mkdir -p $(BUILDDIR)/texinfo
149 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
148 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
150 @echo
149 @echo
151 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
150 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
152 @echo "Run \`make' in that directory to run these through makeinfo" \
151 @echo "Run \`make' in that directory to run these through makeinfo" \
153 "(use \`make info' here to do that automatically)."
152 "(use \`make info' here to do that automatically)."
154
153
155 info:
154 info:
156 mkdir -p $(BUILDDIR)/texinfo
155 mkdir -p $(BUILDDIR)/texinfo
157 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
156 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
158 @echo "Running Texinfo files through makeinfo..."
157 @echo "Running Texinfo files through makeinfo..."
159 make -C $(BUILDDIR)/texinfo info
158 make -C $(BUILDDIR)/texinfo info
160 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
159 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -1,28 +1,32 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2
2
3 from os.path import join, dirname, abspath
3 from os.path import join, dirname, abspath
4
4
5 from IPython.terminal.ipapp import TerminalIPythonApp
5 from IPython.terminal.ipapp import TerminalIPythonApp
6 from ipykernel.kernelapp import IPKernelApp
6 from ipykernel.kernelapp import IPKernelApp
7
7
8 here = abspath(dirname(__file__))
8 here = abspath(dirname(__file__))
9 options = join(here, 'source', 'config', 'options')
9 options = join(here, 'source', 'config', 'options')
10 generated = join(options, 'config-generated.txt')
11
10
12
11 def write_doc(name, title, app, preamble=None):
13 def write_doc(name, title, app, preamble=None):
12 filename = '%s.rst' % name
14 with open(generated, 'a') as f:
13 with open(join(options, filename), 'w') as f:
14 f.write(title + '\n')
15 f.write(title + '\n')
15 f.write(('=' * len(title)) + '\n')
16 f.write(('=' * len(title)) + '\n')
16 f.write('\n')
17 f.write('\n')
17 if preamble is not None:
18 if preamble is not None:
18 f.write(preamble + '\n\n')
19 f.write(preamble + '\n\n')
19 f.write(app.document_config_options())
20 f.write(app.document_config_options())
20
21
21
22
22 if __name__ == '__main__':
23 if __name__ == '__main__':
24 # create empty file
25 with open(generated, 'w'):
26 pass
23
27
24 write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp())
28 write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp())
25 write_doc('kernel', 'IPython kernel options', IPKernelApp(),
29 write_doc('kernel', 'IPython kernel options', IPKernelApp(),
26 preamble=("These options can be used in :file:`ipython_kernel_config.py`. "
30 preamble=("These options can be used in :file:`ipython_kernel_config.py`. "
27 "The kernel also respects any options in `ipython_config.py`"),
31 "The kernel also respects any options in `ipython_config.py`"),
28 )
32 )
@@ -1,12 +1,9 b''
1 ===============
1 ===============
2 IPython options
2 IPython options
3 ===============
3 ===============
4
4
5 Any of the options listed here can be set in config files, at the
5 Any of the options listed here can be set in config files, at the
6 command line, or from inside IPython. See :ref:`setting_config` for
6 command line, or from inside IPython. See :ref:`setting_config` for
7 details.
7 details.
8
8
9 .. toctree::
9 .. include:: config-generated.txt
10
11 terminal
12 kernel
General Comments 0
You need to be logged in to leave comments. Login now