Skip to content

Commit b1895b7

Browse files
dopplershiftdopplershift
committed
MNT: Regenerate sphinx make files
sphinx-build now has a make mode that handles all of the options, so we can have much smaller build scripts. Still need a bit more for clean and autogen, since there's more we need due to sphinx-gallery.
1 parent 41447a8 commit b1895b7

File tree

3 files changed

+30
-396
lines changed

3 files changed

+30
-396
lines changed

‎.travis.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ script:
112112
- if [[ $TASK == "docs" ]]; then
113113
export TEST_DATA_DIR=${TRAVIS_BUILD_DIR}/testdata;
114114
pushd docs;
115-
make clean html linkcheck;
115+
make clean html linkcheck O=-W;
116116
export DOC_BUILD_RESULT=$?;
117117
popd;
118118
if [[ $TRAVIS_PYTHON_VERSION == 3.6* ]]; then

‎docs/Makefile

+16-171
Original file line numberDiff line numberDiff line change
@@ -1,184 +1,29 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

44
# You can set these variables from the command line.
5-
SPHINXOPTS = -W
5+
SPHINXOPTS =
66
SPHINXBUILD = sphinx-build
77
SPHINXAUTOGEN = sphinx-autogen
8-
PAPER =
9-
BUILDDIR = build
10-
HTMLBUILDDIR = $(BUILDDIR)/html
8+
SPHINXPROJ = MetPy
119
SOURCEDIR = .
12-
GITREMOTE = $(shell git config --get remote.docs.url)
13-
14-
# User-friendly check for sphinx-build
15-
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
16-
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
17-
endif
18-
19-
# Internal variables.
20-
PAPEROPT_a4 = -D latex_paper_size=a4
21-
PAPEROPT_letter = -D latex_paper_size=letter
22-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
23-
# the i18n builder cannot share the environment and doctrees with the others
24-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
25-
26-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
10+
BUILDDIR = build
2711

12+
# Put it first so that "make" without argument is like "make help".
2813
help:
29-
@echo "Please use \`make <target>' where <target> is one of"
30-
@echo " html to make standalone HTML files"
31-
@echo " dirhtml to make HTML files named index.html in directories"
32-
@echo " singlehtml to make a single large HTML file"
33-
@echo " pickle to make pickle files"
34-
@echo " json to make JSON files"
35-
@echo " htmlhelp to make HTML files and a HTML help project"
36-
@echo " qthelp to make HTML files and a qthelp project"
37-
@echo " devhelp to make HTML files and a Devhelp project"
38-
@echo " epub to make an epub"
39-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
40-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
41-
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
42-
@echo " text to make text files"
43-
@echo " man to make manual pages"
44-
@echo " texinfo to make Texinfo files"
45-
@echo " info to make Texinfo files and run them through makeinfo"
46-
@echo " gettext to make PO message catalogs"
47-
@echo " changes to make an overview of all changed/added/deprecated items"
48-
@echo " xml to make Docutils-native XML files"
49-
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
50-
@echo " linkcheck to check all external links for integrity"
51-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
14+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
5215

16+
# Sphinx doesn't know to clean out the debris from sphinx-gallery
5317
clean:
5418
rm -rf $(BUILDDIR)/* $(SOURCEDIR)/examples $(SOURCEDIR)/tutorials $(SOURCEDIR)/api/generated
5519

56-
autogen:
57-
$(SPHINXAUTOGEN) -i -t $(SOURCEDIR)/_templates -o $(SOURCEDIR)/api/generated $(SOURCEDIR)/api/*.rst
58-
59-
html: autogen
60-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(HTMLBUILDDIR)
61-
@echo
62-
@echo "Build finished. The HTML pages are in $(HTMLBUILDDIR)."
63-
64-
dirhtml:
65-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
66-
@echo
67-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
68-
69-
singlehtml:
70-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
71-
@echo
72-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
73-
74-
pickle:
75-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
76-
@echo
77-
@echo "Build finished; now you can process the pickle files."
78-
79-
json:
80-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
81-
@echo
82-
@echo "Build finished; now you can process the JSON files."
83-
84-
htmlhelp:
85-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
86-
@echo
87-
@echo "Build finished; now you can run HTML Help Workshop with the" \
88-
".hhp project file in $(BUILDDIR)/htmlhelp."
89-
90-
qthelp:
91-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
92-
@echo
93-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
94-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
95-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MetPy.qhcp"
96-
@echo "To view the help file:"
97-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MetPy.qhc"
98-
99-
devhelp:
100-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
101-
@echo
102-
@echo "Build finished."
103-
@echo "To view the help file:"
104-
@echo "# mkdir -p $$HOME/.local/share/devhelp/MetPy"
105-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MetPy"
106-
@echo "# devhelp"
107-
108-
epub:
109-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
110-
@echo
111-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
112-
113-
latex:
114-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115-
@echo
116-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
117-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
118-
"(use \`make latexpdf' here to do that automatically)."
119-
120-
latexpdf:
121-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
122-
@echo "Running LaTeX files through pdflatex..."
123-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
124-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
125-
126-
latexpdfja:
127-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
128-
@echo "Running LaTeX files through platex and dvipdfmx..."
129-
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
130-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
131-
132-
text:
133-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
134-
@echo
135-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
136-
137-
man:
138-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
139-
@echo
140-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
141-
142-
texinfo:
143-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144-
@echo
145-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
146-
@echo "Run \`make' in that directory to run these through makeinfo" \
147-
"(use \`make info' here to do that automatically)."
148-
149-
info:
150-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
151-
@echo "Running Texinfo files through makeinfo..."
152-
make -C $(BUILDDIR)/texinfo info
153-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
154-
155-
gettext:
156-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
157-
@echo
158-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
159-
160-
changes:
161-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
162-
@echo
163-
@echo "The overview file is in $(BUILDDIR)/changes."
164-
165-
linkcheck:
166-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
167-
@echo
168-
@echo "Link check complete; look for any errors in the above output " \
169-
"or in $(BUILDDIR)/linkcheck/output.txt."
170-
171-
doctest:
172-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
173-
@echo "Testing of doctests in the sources finished, look at the " \
174-
"results in $(BUILDDIR)/doctest/output.txt."
175-
176-
xml:
177-
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
178-
@echo
179-
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
20+
.PHONY: help Makefile
18021

181-
pseudoxml:
182-
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
183-
@echo
184-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
22+
# Catch-all target: route all unknown targets to Sphinx using the new
23+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
24+
# Manual autogen needed so we can specify the -i option so that imported names
25+
# are included in generation
26+
%: Makefile
27+
echo Running sphinx-autogen
28+
@$(SPHINXAUTOGEN) -i -t $(SOURCEDIR)/_templates -o $(SOURCEDIR)/api/generated $(SOURCEDIR)/api/*.rst
29+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

0 commit comments

Comments
 (0)