##// END OF EJS Templates
Finish implementing JSDoc support
Jonathan Frederic -
Show More
@@ -1,162 +1,165 b''
1 1 # Makefile for Sphinx documentation
2 2 #
3 3
4 4 # You can set these variables from the command line.
5 5 SPHINXOPTS =
6 6 SPHINXBUILD = sphinx-build
7 7 PAPER =
8 8 SRCDIR = source
9 9 BUILDDIR = build
10 10
11 11 # Internal variables.
12 12 PAPEROPT_a4 = -D latex_paper_size=a4
13 13 PAPEROPT_letter = -D latex_paper_size=letter
14 14 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
15 15
16 16 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
17 17
18 18 default: html
19 19
20 20 help:
21 21 @echo "Please use \`make <target>' where <target> is one of"
22 22 @echo " html standalone HTML files"
23 23 @echo " html_noapi same as above, without the time consuming API docs"
24 24 @echo " pickle pickle files (usable by e.g. sphinx-web)"
25 25 @echo " htmlhelp HTML files and a HTML help project"
26 26 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
27 27 @echo " texinfo Texinfo files"
28 28 @echo " info Texinfo files and run them through makeinfo"
29 29 @echo " changes an overview over all changed/added/deprecated items"
30 30 @echo " linkcheck check all external links for integrity (takes a long time)"
31 31 @echo
32 32 @echo "Compound utility targets:"
33 33 @echo "pdf latex and then runs the PDF generation"
34 34 @echo "all html and pdf"
35 35 @echo "dist all, and then puts the results in dist/"
36 36 @echo "gitwash-update update git workflow from source repo"
37 37
38 38 clean_api:
39 39 -rm -rf $(SRCDIR)/api/generated
40 40
41 41 clean: clean_api
42 42 -rm -rf build/* dist/*
43 43 -cd $(SRCDIR)/config/options; cat generated | xargs -r rm -f
44 44 -rm -rf $(SRCDIR)/config/options/generated
45 45 -rm -f $(SRCDIR)/interactive/magics-generated.txt
46 46
47 47 pdf: latex
48 48 cd build/latex && make all-pdf
49 49
50 50 all: html pdf
51 51
52 52 # For final distribution, only build HTML (our pdf is now so large as to be
53 53 # unusable, takes forever to build and just bloats the downloads). We leave
54 54 # them hardlinked at the top-level so users find them easily, though the
55 55 # original build/html dir is left in-place (useful to reload builds while
56 56 # testing).
57 57 dist: html
58 58 rm -rf html
59 59 cp -al build/html .
60 60 @echo "Build finished. Final docs are in html/"
61 61
62 html: api autoconfig automagic
62 html: jsapi api autoconfig automagic
63 63 html_noapi: clean_api autoconfig automagic
64 64
65 65 html html_noapi:
66 66 mkdir -p build/html build/doctrees
67 67 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
68 68 @echo
69 69 @echo "Build finished. The HTML pages are in build/html."
70 70
71 71 automagic: source/interactive/magics-generated.txt
72 72
73 73 source/interactive/magics-generated.txt: autogen_magics.py
74 74 python autogen_magics.py
75 75 @echo "Created docs for line & cell magics"
76 76
77 77 autoconfig: source/config/options/generated
78 78
79 79 source/config/options/generated:
80 80 python autogen_config.py
81 81 @echo "Created docs for config options"
82 82
83 jsapi:
84 jsdoc -c jsdoc_config.json -d ./build/jsapi_html/
85
83 86 api: source/api/generated/gen.txt
84 87
85 88 source/api/generated/gen.txt:
86 89 python autogen_api.py
87 90 @echo "Build API docs finished."
88 91
89 92 pickle:
90 93 mkdir -p build/pickle build/doctrees
91 94 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
92 95 @echo
93 96 @echo "Build finished; now you can process the pickle files or run"
94 97 @echo " sphinx-web build/pickle"
95 98 @echo "to start the sphinx-web server."
96 99
97 100 web: pickle
98 101
99 102 htmlhelp:
100 103 mkdir -p build/htmlhelp build/doctrees
101 104 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
102 105 @echo
103 106 @echo "Build finished; now you can run HTML Help Workshop with the" \
104 107 ".hhp project file in build/htmlhelp."
105 108
106 109 qthelp:
107 110 mkdir -p build/qthelp
108 111 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
109 112 @echo
110 113 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
111 114 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
112 115 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
113 116 @echo "To view the help file:"
114 117 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
115 118
116 119 latex: api autoconfig
117 120 mkdir -p build/latex build/doctrees
118 121 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
119 122 @echo
120 123 @echo "Build finished; the LaTeX files are in build/latex."
121 124 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
122 125 "run these through (pdf)latex."
123 126
124 127 changes:
125 128 mkdir -p build/changes build/doctrees
126 129 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
127 130 @echo
128 131 @echo "The overview file is in build/changes."
129 132
130 133 linkcheck:
131 134 mkdir -p build/linkcheck build/doctrees
132 135 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
133 136 @echo
134 137 @echo "Link check complete; look for any errors in the above output " \
135 138 "or in build/linkcheck/output.rst."
136 139
137 140 gitwash-update:
138 141 python ../tools/gitwash_dumper.py source/development ipython
139 142
140 143 nightly: dist
141 144 rsync -avH --delete dist/ ipython:www/doc/nightly
142 145
143 146 gh-pages: clean html
144 147 # if VERSION is unspecified, it will be dev
145 148 # For releases, VERSION should be just the major version,
146 149 # e.g. VERSION=2 make gh-pages
147 150 python gh-pages.py $(VERSION)
148 151
149 152 texinfo:
150 153 mkdir -p $(BUILDDIR)/texinfo
151 154 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
152 155 @echo
153 156 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
154 157 @echo "Run \`make' in that directory to run these through makeinfo" \
155 158 "(use \`make info' here to do that automatically)."
156 159
157 160 info:
158 161 mkdir -p $(BUILDDIR)/texinfo
159 162 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
160 163 @echo "Running Texinfo files through makeinfo..."
161 164 make -C $(BUILDDIR)/texinfo info
162 165 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -1,33 +1,35 b''
1 1 IPython Documentation
2 2 ---------------------
3 3
4 4 This directory contains the majority of the documentation for IPython.
5 5
6 6 Requirements
7 7 ------------
8 8 The following tools are needed to build the documentation:
9 9
10 10 sphinx jsdoc
11 11
12 12 On Debian-based systems, you should be able to run::
13 13
14 sudo apt-get install sphinx npm
14 sudo apt-get install python-sphinx npm
15 15 sudo npm install -g jsdoc@"<=3.3.0"
16 16
17 17 The documentation gets built using ``make``, and comes in several flavors.
18 18
19 ``make html`` - build the API and narrative documentation web pages, this
20 is the the default ``make`` target, so running just ``make`` is equivalent to
21 ``make html``.
19 ``make html`` - build the API (both Javascript and Python) and narrative
20 documentation web pages, this is the the default ``make`` target, so
21 running just ``make`` is equivalent to ``make html``.
22 22
23 23 ``make html_noapi`` - same as above, but without running the auto-generated
24 24 API docs. When you are working on the narrative documentation, the most time
25 25 consuming portion of the build process is the processing and rending of the
26 26 API documentation. This build target skips that.
27 27
28 ``make jsapi`` - build Javascript auto-generated API documents.
29
28 30 ``make pdf`` will compile a pdf from the documentation.
29 31
30 32 You can run ``make help`` to see information on all possible make targets.
31 33
32 34
33 35
@@ -1,16 +1,15 b''
1 1 {
2 2 "tags": {
3 3 "allowUnknownTags": true
4 4 },
5 5 "source": {
6 6 "include": [
7 7 "../IPython/html/static/notebook/js/notebook.js"
8 8 ]
9 9 },
10 10 "plugins": [],
11 11 "templates": {
12 12 "cleverLinks": false,
13 13 "monospaceLinks": false
14 },
15 "destination": "./out/"
14 }
16 15 } No newline at end of file
@@ -1,71 +1,77 b''
1 1 @ECHO OFF
2 2 REM ~ Windows command line make file for Sphinx documentation
3 3
4 4 SETLOCAL
5 5
6 6 SET SPHINXOPTS=
7 7 SET SPHINXBUILD=sphinx-build
8 SET JSDOC=jsdoc
8 9 SET PAPER=
9 10 SET SRCDIR=source
10 11
11 12 IF "%PAPER%" == "" SET PAPER=a4
12 13 SET ALLSPHINXOPTS=-d build\doctrees -D latex_paper_size=%PAPER% %SPHINXOPTS% %SRCDIR%
13 14
14 15 FOR %%X IN (%SPHINXBUILD%.exe) DO SET P=%%~$PATH:X
15 16
16 17 FOR %%L IN (html pickle htmlhelp latex changes linkcheck) DO (
17 18 IF "%1" == "%%L" (
18 19 IF "%P%" == "" (
19 20 ECHO.
20 21 ECHO Error: Sphinx is not available. Please make sure it is correctly installed.
21 22 GOTO END
22 23 )
23 24 MD build\doctrees 2>NUL
24 25 MD build\%1 || GOTO DIR_EXIST
25 26 %SPHINXBUILD% -b %1 %ALLSPHINXOPTS% build\%1
26 27 IF NOT ERRORLEVEL 0 GOTO ERROR
27 28 ECHO.
28 29 ECHO Build finished. Results are in build\%1.
29 30 IF "%1" == "pickle" (
30 31 ECHO Now you can process the pickle files or run
31 32 ECHO sphinx-web build\pickle to start the sphinx-web server.
32 33 )
33 34 IF "%1" == "htmlhelp" (
34 35 ECHO Now you can run HTML Help Workshop with the
35 36 ECHO .hhp project file in build/htmlhelp.
36 37 )
37 38 IF "%1" == "linkcheck" (
38 39 ECHO Look for any errors in the above output
39 40 ECHO or in build\linkcheck\output.rst.
40 41 )
41 42 GOTO END
42 43 )
43 44 )
44 45
45 46 IF "%1" == "clean" (
47 %JSDOC% -c jsdoc_config.json -d ./build/jsapi_html/
48 )
49
50 IF "%1" == "jsapi" (
46 51 RD /s /q build dist %SRCDIR%\api\generated 2>NUL
47 52 IF ERRORLEVEL 0 ECHO Build environment cleaned!
48 53 GOTO END
49 54 )
50 55
51 56 ECHO.
52 57 ECHO Please use "make [target]" where [target] is one of:
53 58 ECHO.
54 59 ECHO html to make standalone HTML files
60 ECHO jsapi to make standalone HTML files for the Javascript API
55 61 ECHO pickle to make pickle files (usable by e.g. sphinx-web)
56 62 ECHO htmlhelp to make HTML files and a HTML help project
57 63 ECHO latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
58 64 ECHO changes to make an overview over all changed/added/deprecated items
59 65 ECHO linkcheck to check all external links for integrity
60 66 GOTO END
61 67
62 68 :DIR_EXIST
63 69 ECHO.
64 70 ECHO Info: Run "make clean" to clean build environment
65 71
66 72 :ERROR
67 73 ECHO.
68 74 ECHO Error: Build process failed!
69 75
70 76 :END
71 77 ENDLOCAL No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now