Skip to content
This repository was archived by the owner on Sep 24, 2021. It is now read-only.

Commit 40c3bbc

Browse files
ocefpafocefpaf
committed
build docs
1 parent 511a923 commit 40c3bbc

File tree

5 files changed

+455
-169
lines changed

5 files changed

+455
-169
lines changed

‎docs/Makefile

Lines changed: 171 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,82 +8,234 @@ PAPER =
88
BUILDDIR = _build
99

1010
# Internal variables.
11-
PAPEROPT_a4 = -D latex_paper_size=a4
12-
PAPEROPT_letter = -D latex_paper_size=letter
11+
PAPEROPT_a4 = -D latex_elements.papersize=a4
12+
PAPEROPT_letter = -D latex_elements.papersize=letter
1313
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14+
# the i18n builder cannot share the environment and doctrees with the others
15+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
1416

15-
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
16-
17+
.PHONY: help
1718
help:
1819
@echo "Please use \`make <target>' where <target> is one of"
19-
@echo " html to make standalone HTML files"
20-
@echo " dirhtml to make HTML files named index.html in directories"
21-
@echo " pickle to make pickle files"
22-
@echo " json to make JSON files"
23-
@echo " htmlhelp to make HTML files and a HTML help project"
24-
@echo " qthelp to make HTML files and a qthelp project"
25-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
26-
@echo " changes to make an overview of all changed/added/deprecated items"
27-
@echo " linkcheck to check all external links for integrity"
28-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
20+
@echo " html to make standalone HTML files"
21+
@echo " dirhtml to make HTML files named index.html in directories"
22+
@echo " singlehtml to make a single large HTML file"
23+
@echo " pickle to make pickle files"
24+
@echo " json to make JSON files"
25+
@echo " htmlhelp to make HTML files and an HTML help project"
26+
@echo " qthelp to make HTML files and a qthelp project"
27+
@echo " applehelp to make an Apple Help Book"
28+
@echo " devhelp to make HTML files and a Devhelp project"
29+
@echo " epub to make an epub"
30+
@echo " epub3 to make an epub3"
31+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
32+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
33+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
34+
@echo " lualatexpdf to make LaTeX files and run them through lualatex"
35+
@echo " xelatexpdf to make LaTeX files and run them through xelatex"
36+
@echo " text to make text files"
37+
@echo " man to make manual pages"
38+
@echo " texinfo to make Texinfo files"
39+
@echo " info to make Texinfo files and run them through makeinfo"
40+
@echo " gettext to make PO message catalogs"
41+
@echo " changes to make an overview of all changed/added/deprecated items"
42+
@echo " xml to make Docutils-native XML files"
43+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
44+
@echo " linkcheck to check all external links for integrity"
45+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
46+
@echo " coverage to run coverage check of the documentation (if enabled)"
47+
@echo " dummy to check syntax errors of document sources"
2948

49+
.PHONY: clean
3050
clean:
31-
-rm -rf $(BUILDDIR)/*
51+
rm -rf $(BUILDDIR)/*
3252

53+
.PHONY: html
3354
html:
3455
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
3556
@echo
3657
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
3758

59+
.PHONY: dirhtml
3860
dirhtml:
3961
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
4062
@echo
4163
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
4264

65+
.PHONY: singlehtml
66+
singlehtml:
67+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
68+
@echo
69+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
70+
71+
.PHONY: pickle
4372
pickle:
4473
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
4574
@echo
4675
@echo "Build finished; now you can process the pickle files."
4776

77+
.PHONY: json
4878
json:
4979
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
5080
@echo
5181
@echo "Build finished; now you can process the JSON files."
5282

83+
.PHONY: htmlhelp
5384
htmlhelp:
5485
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
5586
@echo
5687
@echo "Build finished; now you can run HTML Help Workshop with the" \
5788
".hhp project file in $(BUILDDIR)/htmlhelp."
5889

90+
.PHONY: qthelp
5991
qthelp:
6092
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
6193
@echo
6294
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
6395
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
64-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/seawater.qhcp"
96+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/gsw.qhcp"
6597
@echo "To view the help file:"
66-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/seawater.qhc"
98+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/gsw.qhc"
99+
100+
.PHONY: applehelp
101+
applehelp:
102+
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
103+
@echo
104+
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
105+
@echo "N.B. You won't be able to view it unless you put it in" \
106+
"~/Library/Documentation/Help or install it in your application" \
107+
"bundle."
108+
109+
.PHONY: devhelp
110+
devhelp:
111+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
112+
@echo
113+
@echo "Build finished."
114+
@echo "To view the help file:"
115+
@echo "# mkdir -p $$HOME/.local/share/devhelp/gsw"
116+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/gsw"
117+
@echo "# devhelp"
118+
119+
.PHONY: epub
120+
epub:
121+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
122+
@echo
123+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
124+
125+
.PHONY: epub3
126+
epub3:
127+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
128+
@echo
129+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
67130

131+
.PHONY: latex
68132
latex:
69133
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
70134
@echo
71135
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
72-
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
73-
"run these through (pdf)latex."
136+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
137+
"(use \`make latexpdf' here to do that automatically)."
138+
139+
.PHONY: latexpdf
140+
latexpdf:
141+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
142+
@echo "Running LaTeX files through pdflatex..."
143+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
144+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
145+
146+
.PHONY: latexpdfja
147+
latexpdfja:
148+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
149+
@echo "Running LaTeX files through platex and dvipdfmx..."
150+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
151+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
152+
153+
.PHONY: lualatexpdf
154+
lualatexpdf:
155+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
156+
@echo "Running LaTeX files through lualatex..."
157+
$(MAKE) PDFLATEX=lualatex -C $(BUILDDIR)/latex all-pdf
158+
@echo "lualatex finished; the PDF files are in $(BUILDDIR)/latex."
74159

160+
.PHONY: xelatexpdf
161+
xelatexpdf:
162+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
163+
@echo "Running LaTeX files through xelatex..."
164+
$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf
165+
@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
166+
167+
.PHONY: text
168+
text:
169+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
170+
@echo
171+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
172+
173+
.PHONY: man
174+
man:
175+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
176+
@echo
177+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
178+
179+
.PHONY: texinfo
180+
texinfo:
181+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
182+
@echo
183+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
184+
@echo "Run \`make' in that directory to run these through makeinfo" \
185+
"(use \`make info' here to do that automatically)."
186+
187+
.PHONY: info
188+
info:
189+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
190+
@echo "Running Texinfo files through makeinfo..."
191+
make -C $(BUILDDIR)/texinfo info
192+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
193+
194+
.PHONY: gettext
195+
gettext:
196+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
197+
@echo
198+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
199+
200+
.PHONY: changes
75201
changes:
76202
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
77203
@echo
78204
@echo "The overview file is in $(BUILDDIR)/changes."
79205

206+
.PHONY: linkcheck
80207
linkcheck:
81208
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
82209
@echo
83210
@echo "Link check complete; look for any errors in the above output " \
84211
"or in $(BUILDDIR)/linkcheck/output.txt."
85212

213+
.PHONY: doctest
86214
doctest:
87215
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
88216
@echo "Testing of doctests in the sources finished, look at the " \
89217
"results in $(BUILDDIR)/doctest/output.txt."
218+
219+
.PHONY: coverage
220+
coverage:
221+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
222+
@echo "Testing of coverage in the sources finished, look at the " \
223+
"results in $(BUILDDIR)/coverage/python.txt."
224+
225+
.PHONY: xml
226+
xml:
227+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
228+
@echo
229+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
230+
231+
.PHONY: pseudoxml
232+
pseudoxml:
233+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
234+
@echo
235+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
236+
237+
.PHONY: dummy
238+
dummy:
239+
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
240+
@echo
241+
@echo "Build finished. Dummy builder generates no files."

0 commit comments

Comments
 (0)