##// END OF EJS Templates
Merge pull request #5516 from yarikoptic/upstream-master...
Thomas Kluyver -
r16202:2cb5efa1 merge
parent child Browse files
Show More
@@ -1,154 +1,155 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
10
11 # Internal variables.
11 # Internal variables.
12 PAPEROPT_a4 = -D latex_paper_size=a4
12 PAPEROPT_a4 = -D latex_paper_size=a4
13 PAPEROPT_letter = -D latex_paper_size=letter
13 PAPEROPT_letter = -D latex_paper_size=letter
14 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
14 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
15
15
16 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
16 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
17
17
18 default: html
18 default: html
19
19
20 help:
20 help:
21 @echo "Please use \`make <target>' where <target> is one of"
21 @echo "Please use \`make <target>' where <target> is one of"
22 @echo " html standalone HTML files"
22 @echo " html standalone HTML files"
23 @echo " html_noapi same as above, without the time consuming API docs"
23 @echo " html_noapi same as above, without the time consuming API docs"
24 @echo " pickle pickle files (usable by e.g. sphinx-web)"
24 @echo " pickle pickle files (usable by e.g. sphinx-web)"
25 @echo " htmlhelp HTML files and a HTML help project"
25 @echo " htmlhelp HTML files and a HTML help project"
26 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
26 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
27 @echo " texinfo Texinfo files"
27 @echo " texinfo Texinfo files"
28 @echo " info Texinfo files and run them through makeinfo"
28 @echo " info Texinfo files and run them through makeinfo"
29 @echo " changes an overview over all changed/added/deprecated items"
29 @echo " changes an overview over all changed/added/deprecated items"
30 @echo " linkcheck check all external links for integrity (takes a long time)"
30 @echo " linkcheck check all external links for integrity (takes a long time)"
31 @echo
31 @echo
32 @echo "Compound utility targets:"
32 @echo "Compound utility targets:"
33 @echo "pdf latex and then runs the PDF generation"
33 @echo "pdf latex and then runs the PDF generation"
34 @echo "all html and pdf"
34 @echo "all html and pdf"
35 @echo "dist all, and then puts the results in dist/"
35 @echo "dist all, and then puts the results in dist/"
36 @echo "gitwash-update update git workflow from source repo"
36 @echo "gitwash-update update git workflow from source repo"
37
37
38 clean_api:
38 clean_api:
39 -rm -rf $(SRCDIR)/api/generated
39 -rm -rf $(SRCDIR)/api/generated
40
40
41 clean: clean_api
41 clean: clean_api
42 -rm -rf build/* dist/*
42 -rm -rf build/* dist/*
43 -cd $(SRCDIR)/config/options; cat generated | xargs -r rm -f
43 -rm -rf $(SRCDIR)/config/options/generated
44 -rm -rf $(SRCDIR)/config/options/generated
44
45
45 pdf: latex
46 pdf: latex
46 cd build/latex && make all-pdf
47 cd build/latex && make all-pdf
47
48
48 all: html pdf
49 all: html pdf
49
50
50 # For final distribution, only build HTML (our pdf is now so large as to be
51 # For final distribution, only build HTML (our pdf is now so large as to be
51 # unusable, takes forever to build and just bloats the downloads). We leave
52 # unusable, takes forever to build and just bloats the downloads). We leave
52 # them hardlinked at the top-level so users find them easily, though the
53 # them hardlinked at the top-level so users find them easily, though the
53 # original build/html dir is left in-place (useful to reload builds while
54 # original build/html dir is left in-place (useful to reload builds while
54 # testing).
55 # testing).
55 dist: html
56 dist: html
56 rm -rf html
57 rm -rf html
57 cp -al build/html .
58 cp -al build/html .
58 @echo "Build finished. Final docs are in html/"
59 @echo "Build finished. Final docs are in html/"
59
60
60 html: api autoconfig
61 html: api autoconfig
61 html_noapi: clean_api autoconfig
62 html_noapi: clean_api autoconfig
62
63
63 html html_noapi:
64 html html_noapi:
64 mkdir -p build/html build/doctrees
65 mkdir -p build/html build/doctrees
65 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
66 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
66 @echo
67 @echo
67 @echo "Build finished. The HTML pages are in build/html."
68 @echo "Build finished. The HTML pages are in build/html."
68
69
69 autoconfig: source/config/options/generated
70 autoconfig: source/config/options/generated
70
71
71 source/config/options/generated:
72 source/config/options/generated:
72 python autogen_config.py
73 python autogen_config.py
73 @echo "Created docs for config options"
74 @echo "Created docs for config options"
74
75
75 api: source/api/generated/gen.txt
76 api: source/api/generated/gen.txt
76
77
77 source/api/generated/gen.txt:
78 source/api/generated/gen.txt:
78 python autogen_api.py
79 python autogen_api.py
79 @echo "Build API docs finished."
80 @echo "Build API docs finished."
80
81
81 pickle:
82 pickle:
82 mkdir -p build/pickle build/doctrees
83 mkdir -p build/pickle build/doctrees
83 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
84 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
84 @echo
85 @echo
85 @echo "Build finished; now you can process the pickle files or run"
86 @echo "Build finished; now you can process the pickle files or run"
86 @echo " sphinx-web build/pickle"
87 @echo " sphinx-web build/pickle"
87 @echo "to start the sphinx-web server."
88 @echo "to start the sphinx-web server."
88
89
89 web: pickle
90 web: pickle
90
91
91 htmlhelp:
92 htmlhelp:
92 mkdir -p build/htmlhelp build/doctrees
93 mkdir -p build/htmlhelp build/doctrees
93 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
94 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
94 @echo
95 @echo
95 @echo "Build finished; now you can run HTML Help Workshop with the" \
96 @echo "Build finished; now you can run HTML Help Workshop with the" \
96 ".hhp project file in build/htmlhelp."
97 ".hhp project file in build/htmlhelp."
97
98
98 qthelp:
99 qthelp:
99 mkdir -p build/qthelp
100 mkdir -p build/qthelp
100 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
101 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
101 @echo
102 @echo
102 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
103 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
103 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
104 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
104 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
105 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
105 @echo "To view the help file:"
106 @echo "To view the help file:"
106 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
107 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
107
108
108 latex: api autoconfig
109 latex: api autoconfig
109 mkdir -p build/latex build/doctrees
110 mkdir -p build/latex build/doctrees
110 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
111 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
111 @echo
112 @echo
112 @echo "Build finished; the LaTeX files are in build/latex."
113 @echo "Build finished; the LaTeX files are in build/latex."
113 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
114 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
114 "run these through (pdf)latex."
115 "run these through (pdf)latex."
115
116
116 changes:
117 changes:
117 mkdir -p build/changes build/doctrees
118 mkdir -p build/changes build/doctrees
118 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
119 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
119 @echo
120 @echo
120 @echo "The overview file is in build/changes."
121 @echo "The overview file is in build/changes."
121
122
122 linkcheck:
123 linkcheck:
123 mkdir -p build/linkcheck build/doctrees
124 mkdir -p build/linkcheck build/doctrees
124 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
125 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
125 @echo
126 @echo
126 @echo "Link check complete; look for any errors in the above output " \
127 @echo "Link check complete; look for any errors in the above output " \
127 "or in build/linkcheck/output.rst."
128 "or in build/linkcheck/output.rst."
128
129
129 gitwash-update:
130 gitwash-update:
130 python ../tools/gitwash_dumper.py source/development ipython
131 python ../tools/gitwash_dumper.py source/development ipython
131
132
132 nightly: dist
133 nightly: dist
133 rsync -avH --delete dist/ ipython:www/doc/nightly
134 rsync -avH --delete dist/ ipython:www/doc/nightly
134
135
135 gh-pages: clean html
136 gh-pages: clean html
136 # if VERSION is unspecified, it will be dev
137 # if VERSION is unspecified, it will be dev
137 # For releases, VERSION should be just the major version,
138 # For releases, VERSION should be just the major version,
138 # e.g. VERSION=2 make gh-pages
139 # e.g. VERSION=2 make gh-pages
139 python gh-pages.py $(VERSION)
140 python gh-pages.py $(VERSION)
140
141
141 texinfo:
142 texinfo:
142 mkdir -p $(BUILDDIR)/texinfo
143 mkdir -p $(BUILDDIR)/texinfo
143 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144 @echo
145 @echo
145 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
146 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
146 @echo "Run \`make' in that directory to run these through makeinfo" \
147 @echo "Run \`make' in that directory to run these through makeinfo" \
147 "(use \`make info' here to do that automatically)."
148 "(use \`make info' here to do that automatically)."
148
149
149 info:
150 info:
150 mkdir -p $(BUILDDIR)/texinfo
151 mkdir -p $(BUILDDIR)/texinfo
151 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
152 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
152 @echo "Running Texinfo files through makeinfo..."
153 @echo "Running Texinfo files through makeinfo..."
153 make -C $(BUILDDIR)/texinfo info
154 make -C $(BUILDDIR)/texinfo info
154 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
155 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -1,80 +1,88 b''
1 #!/usr/bin/env python
2
1 from IPython.utils.text import indent, wrap_paragraphs
3 from IPython.utils.text import indent, wrap_paragraphs
2
4
3 from IPython.terminal.ipapp import TerminalIPythonApp
5 from IPython.terminal.ipapp import TerminalIPythonApp
4 from IPython.kernel.zmq.kernelapp import IPKernelApp
6 from IPython.kernel.zmq.kernelapp import IPKernelApp
5 from IPython.html.notebookapp import NotebookApp
7 from IPython.html.notebookapp import NotebookApp
6
8
7 def document_config_options(classes):
9 def document_config_options(classes):
8 lines = []
10 lines = []
9 for cls in classes:
11 for cls in classes:
10 classname = cls.__name__
12 classname = cls.__name__
11 for k, trait in sorted(cls.class_traits(config=True).items()):
13 for k, trait in sorted(cls.class_traits(config=True).items()):
12 ttype = trait.__class__.__name__
14 ttype = trait.__class__.__name__
13
15
14 termline = classname + '.' + trait.name
16 termline = classname + '.' + trait.name
15
17
16 # Choices or type
18 # Choices or type
17 if 'Enum' in ttype:
19 if 'Enum' in ttype:
18 # include Enum choices
20 # include Enum choices
19 termline += ' : ' + '|'.join(repr(x) for x in trait.values)
21 termline += ' : ' + '|'.join(repr(x) for x in trait.values)
20 else:
22 else:
21 termline += ' : ' + ttype
23 termline += ' : ' + ttype
22 lines.append(termline)
24 lines.append(termline)
23
25
24 # Default value
26 # Default value
25 try:
27 try:
26 dv = trait.get_default_value()
28 dv = trait.get_default_value()
27 dvr = repr(dv)
29 dvr = repr(dv)
28 except Exception:
30 except Exception:
29 dvr = dv = None # ignore defaults we can't construct
31 dvr = dv = None # ignore defaults we can't construct
30 if (dv is not None) and (dvr is not None):
32 if (dv is not None) and (dvr is not None):
31 if len(dvr) > 64:
33 if len(dvr) > 64:
32 dvr = dvr[:61]+'...'
34 dvr = dvr[:61]+'...'
33 # Double up backslashes, so they get to the rendered docs
35 # Double up backslashes, so they get to the rendered docs
34 dvr = dvr.replace('\\n', '\\\\n')
36 dvr = dvr.replace('\\n', '\\\\n')
35 lines.append(' Default: ' + dvr)
37 lines.append(' Default: ' + dvr)
36 lines.append('')
38 lines.append('')
37
39
38 help = trait.get_metadata('help')
40 help = trait.get_metadata('help')
39 if help is not None:
41 if help is not None:
40 help = '\n\n'.join(wrap_paragraphs(help, 76))
42 help = '\n\n'.join(wrap_paragraphs(help, 76))
41 lines.append(indent(help, 4))
43 lines.append(indent(help, 4))
42 else:
44 else:
43 lines.append(' No description')
45 lines.append(' No description')
44
46
45 lines.append('')
47 lines.append('')
46 return '\n'.join(lines)
48 return '\n'.join(lines)
47
49
48 kernel_classes = IPKernelApp().classes
50 kernel_classes = IPKernelApp().classes
49
51
50 def write_doc(filename, title, classes, preamble=None):
52 def write_doc(name, title, classes, preamble=None):
51 configdoc = document_config_options(classes)
53 configdoc = document_config_options(classes)
52 with open('source/config/options/%s.rst' % filename, 'w') as f:
54 filename = '%s.rst' % name
55 with open('source/config/options/%s' % filename, 'w') as f:
53 f.write(title + '\n')
56 f.write(title + '\n')
54 f.write(('=' * len(title)) + '\n')
57 f.write(('=' * len(title)) + '\n')
55 f.write('\n')
58 f.write('\n')
56 if preamble is not None:
59 if preamble is not None:
57 f.write(preamble + '\n\n')
60 f.write(preamble + '\n\n')
58 f.write(configdoc)
61 f.write(configdoc)
62 with open('source/config/options/generated', 'a') as f:
63 f.write(filename + '\n')
64
59
65
60 if __name__ == '__main__':
66 if __name__ == '__main__':
67 # create empty file
68 with open('source/config/options/generated', 'w'):
69 pass
70
61 write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp().classes)
71 write_doc('terminal', 'Terminal IPython options', TerminalIPythonApp().classes)
62 write_doc('kernel', 'IPython kernel options', kernel_classes,
72 write_doc('kernel', 'IPython kernel options', kernel_classes,
63 preamble="These options can be used in :file:`ipython_notebook_config.py` "
73 preamble="These options can be used in :file:`ipython_notebook_config.py` "
64 "or in :file:`ipython_qtconsole_config.py`")
74 "or in :file:`ipython_qtconsole_config.py`")
65 nbclasses = set(NotebookApp().classes) - set(kernel_classes)
75 nbclasses = set(NotebookApp().classes) - set(kernel_classes)
66 write_doc('notebook', 'IPython notebook options', nbclasses,
76 write_doc('notebook', 'IPython notebook options', nbclasses,
67 preamble="Any of the :doc:`kernel` can also be used.")
77 preamble="Any of the :doc:`kernel` can also be used.")
68
78
69 try:
79 try:
70 from IPython.qt.console.qtconsoleapp import IPythonQtConsoleApp
80 from IPython.qt.console.qtconsoleapp import IPythonQtConsoleApp
71 except ImportError:
81 except ImportError:
72 print("WARNING: Could not import qtconsoleapp. Config options for the "
82 print("WARNING: Could not import qtconsoleapp. Config options for the "
73 "Qt Console will not be documented.")
83 "Qt Console will not be documented.")
74 else:
84 else:
75 qtclasses = set(IPythonQtConsoleApp().classes) - set(kernel_classes)
85 qtclasses = set(IPythonQtConsoleApp().classes) - set(kernel_classes)
76 write_doc('qtconsole', 'IPython Qt console options', qtclasses,
86 write_doc('qtconsole', 'IPython Qt console options', qtclasses,
77 preamble="Any of the :doc:`kernel` can also be used.")
87 preamble="Any of the :doc:`kernel` can also be used.")
78
88
79 with open('source/config/options/generated', 'w'):
80 pass No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now