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