...
|
...
|
@@ -1,183 +1,40 @@
|
1
|
|
-# Makefile for Sphinx documentation
|
2
|
|
-
|
3
|
|
-# Copyright 2011-2017 Kwant authors.
|
|
1
|
+# Minimal makefile for Sphinx documentation
|
4
|
2
|
#
|
5
|
|
-# This file is part of Kwant. It is subject to the license terms in the file
|
6
|
|
-# LICENSE.rst found in the top-level directory of this distribution and at
|
7
|
|
-# http://kwant-project.org/license. A list of Kwant authors can be found in
|
8
|
|
-# the file AUTHORS.rst at the top-level directory of this distribution and at
|
9
|
|
-# http://kwant-project.org/authors.
|
10
|
3
|
|
11
|
4
|
# You can set these variables from the command line.
|
12
|
5
|
SPHINXOPTS =
|
13
|
|
-SPHINXBUILD = python3 -c 'import sys, sphinx; sys.exit(sphinx.main(sys.argv))'
|
14
|
|
-PAPER =
|
|
6
|
+SPHINXBUILD = sphinx-build
|
|
7
|
+SOURCEDIR = source
|
15
|
8
|
BUILDDIR = build
|
16
|
9
|
|
17
|
|
-# Internal variables.
|
18
|
|
-PAPEROPT_a4 = -D latex_paper_size=a4
|
19
|
|
-PAPEROPT_letter = -D latex_paper_size=letter
|
20
|
|
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
|
|
10
|
+# Put it first so that "make" without argument is like "make help".
|
|
11
|
+help:
|
|
12
|
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
13
|
+
|
|
14
|
+.PHONY: help Makefile
|
21
|
15
|
|
22
|
16
|
# We convert all SVG files to PDF for LaTeX output. For HTML output, we don't
|
23
|
17
|
# create PNGs but rather use the SVG files directly.
|
24
|
18
|
FIGURESOURCES = $(shell find source -name "*.svg")
|
25
|
19
|
GENERATEDPDF = $(patsubst %.svg,%.pdf,$(FIGURESOURCES))
|
26
|
20
|
|
27
|
|
-# Figure generation from patched tutorial scripts
|
28
|
|
-#
|
29
|
|
-# As make does not support the generation of multiple targets by a single
|
30
|
|
-# invocation of a (non-implicit) rule, we use a trick: We pretend to be
|
31
|
|
-# generating a single (empty) flag file per invocation. The figure files are
|
32
|
|
-# generated as well, but only as side-effects. Each flag file is used to
|
33
|
|
-# remember the time at which the corresponding figure-generating script was run.
|
34
|
|
-# This works perfectly unless the actual output files are deleted without
|
35
|
|
-# deleting the corresponding flag file.
|
36
|
|
-FIGSCRIPTS = $(patsubst %.diff,%,$(notdir $(wildcard source/code/figure/*.py.diff)))
|
37
|
|
-FIGURES = $(patsubst %.py,source/code/figure/.%_flag,$(FIGSCRIPTS))
|
38
|
|
-SCRIPTS = $(sort $(FIGSCRIPTS) $(notdir $(wildcard source/code/include/*.py)))
|
39
|
|
-INCLUDES = $(patsubst %,source/code/include/%,$(SCRIPTS))
|
40
|
|
-DOWNLOADS = $(patsubst %,source/code/download/%,$(SCRIPTS))
|
41
|
|
-
|
42
|
|
-.PHONY: help clean realclean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
|
43
|
|
-
|
44
|
|
-help:
|
45
|
|
- @echo "Please use \`make <target>' where <target> is one of"
|
46
|
|
- @echo " html to make standalone HTML files"
|
47
|
|
- @echo " dirhtml to make HTML files named index.html in directories"
|
48
|
|
- @echo " pickle to make pickle files"
|
49
|
|
- @echo " json to make JSON files"
|
50
|
|
- @echo " htmlhelp to make HTML files and a HTML help project"
|
51
|
|
- @echo " qthelp to make HTML files and a qthelp project"
|
52
|
|
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
53
|
|
- @echo " changes to make an overview of all changed/added/deprecated items"
|
54
|
|
- @echo " linkcheck to check all external links for integrity"
|
55
|
|
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
56
|
|
- @echo
|
57
|
|
- @echo "Append SPHINXOPTS='-A website_deploy=True' to include web analytics code."
|
58
|
|
-
|
59
|
|
-clean:
|
60
|
|
- -rm -rf $(BUILDDIR)/* $(GENERATEDPDF)
|
61
|
|
- -rm -rf source/reference/generated
|
62
|
|
-
|
63
|
|
-realclean: clean
|
64
|
|
- -rm -f $(FIGURES)
|
65
|
|
- -rm -f $(patsubst %,source/code/include/%,$(FIGSCRIPTS))
|
66
|
|
- -rm -f $(DOWNLOADS)
|
67
|
|
- -rm -f $(patsubst %,source/code/figure/%,$(FIGSCRIPTS))
|
68
|
|
- -rm -f $(patsubst %.py,source/code/figure/%_*.png,$(FIGSCRIPTS))
|
69
|
|
- -rm -f $(patsubst %.py,source/code/figure/%_*.pdf,$(FIGSCRIPTS))
|
70
|
|
-
|
71
|
|
-html: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
72
|
|
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
73
|
|
- @echo
|
74
|
|
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
75
|
|
-
|
76
|
|
-dirhtml: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
77
|
|
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
78
|
|
- @echo
|
79
|
|
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
80
|
|
-
|
81
|
|
-pickle: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
82
|
|
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
83
|
|
- @echo
|
84
|
|
- @echo "Build finished; now you can process the pickle files."
|
85
|
|
-
|
86
|
|
-json: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
87
|
|
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
88
|
|
- @echo
|
89
|
|
- @echo "Build finished; now you can process the JSON files."
|
90
|
|
-
|
91
|
|
-htmlhelp: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
92
|
|
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
93
|
|
- @echo
|
94
|
|
- @echo "Build finished; now you can run HTML Help Workshop with the" \
|
95
|
|
- ".hhp project file in $(BUILDDIR)/htmlhelp."
|
96
|
|
-
|
97
|
|
-qthelp: $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
98
|
|
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
99
|
|
- @echo
|
100
|
|
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
101
|
|
- ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
102
|
|
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/kwant.qhcp"
|
103
|
|
- @echo "To view the help file:"
|
104
|
|
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/kwant.qhc"
|
105
|
|
-
|
106
|
|
-latex: $(GENERATEDPDF) $(FIGURES) $(INCLUDES) $(DOWNLOADS)
|
107
|
|
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
108
|
|
- @echo
|
109
|
|
- @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
110
|
|
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
|
111
|
|
- "run these through (pdf)latex."
|
112
|
|
-
|
113
|
|
-changes:
|
114
|
|
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
115
|
|
- @echo
|
116
|
|
- @echo "The overview file is in $(BUILDDIR)/changes."
|
117
|
|
-
|
118
|
|
-linkcheck:
|
119
|
|
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
120
|
|
- @echo
|
121
|
|
- @echo "Link check complete; look for any errors in the above output " \
|
122
|
|
- "or in $(BUILDDIR)/linkcheck/output.txt."
|
123
|
|
-
|
124
|
|
-doctest:
|
125
|
|
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
126
|
|
- @echo "Testing of doctests in the sources finished, look at the " \
|
127
|
|
- "results in $(BUILDDIR)/doctest/output.txt."
|
128
|
|
-
|
129
|
21
|
%.pdf: %.svg
|
130
|
22
|
inkscape --export-pdf=$@ $<
|
131
|
23
|
|
132
|
|
-#### Tutorial and figure script generation machinery ####
|
133
|
|
-# See source/code/README for an explanation.
|
134
|
|
-
|
135
|
|
-# Make tutorial scripts by extracting the (complete!) context of the "patches".
|
136
|
|
-# We make sure not to use 'wiggle' here.
|
137
|
|
-.SECONDARY:
|
138
|
|
-source/code/include/%.py: source/code/figure/%.py.diff
|
139
|
|
- @sed -n '/^[- ]/ s/^.//p' <$< >$@
|
140
|
|
- @touch -r $< $@
|
|
24
|
+# Emtpy target required so that the default target is not triggered
|
|
25
|
+%.svg:
|
141
|
26
|
|
142
|
|
-source/code/download/%.py: source/code/include/%.py
|
143
|
|
- @mkdir -p source/code/download
|
144
|
|
- @grep -v '^#HIDDEN' <$< >$@
|
145
|
27
|
|
146
|
|
-# Make the figure generation scripts by patching tutorial scripts. If the
|
147
|
|
-# tutorial scripts haven't been modified, don't patch but directly extract the
|
148
|
|
-# figure generation scripts. This means that 'wiggle' is only needed when the
|
149
|
|
-# tutorial scripts have been modified.
|
150
|
|
-.SECONDARY:
|
151
|
|
-source/code/figure/%.py: source/code/include/%.py
|
152
|
|
- @if [ $< -nt $@.diff ]; then \
|
153
|
|
- cp $< $@; \
|
154
|
|
- rm -f $@.porig; \
|
155
|
|
- if ! wiggle --replace $@ $@.diff; then \
|
156
|
|
- command -v wiggle >/dev/null 2>&1 && \
|
157
|
|
- echo "Resolve conflicts by editing the files named below"; \
|
158
|
|
- touch -d@0 $@; \
|
159
|
|
- exit 1; \
|
160
|
|
- fi \
|
161
|
|
- else \
|
162
|
|
- sed -n '/^[+ ]/ s/^.//p' <$@.diff >$@; \
|
163
|
|
- touch -r $@.diff $@; \
|
164
|
|
- fi
|
165
|
|
-
|
166
|
|
-# Make the figure generation scripts also depend on the diffs.
|
167
|
|
-define makedep
|
168
|
|
-source/code/figure/$(1): source/code/figure/$(1).diff
|
169
|
|
-endef
|
170
|
|
-$(foreach name,$(FIGSCRIPTS),$(eval $(call makedep,$(name))))
|
171
|
|
-
|
172
|
|
-# Run an figure generation script. When successful, and if the script is newer
|
173
|
|
-# than the corresponding diff, recreate the latter. Note that the
|
174
|
|
-# corresponding tutorial script cannot be newer, since if it is, the figure
|
175
|
|
-# generation script is generated from it by patching.
|
176
|
|
-source/code/figure/.%_flag: source/code/figure/%.py
|
177
|
|
- cd $(dir $<) && python3 $(notdir $<)
|
178
|
|
- @if [ ! -f $<.diff -o $< -nt $<.diff ]; then \
|
179
|
|
- wiggle --diff --lines source/code/include/$(notdir $<) $< >$<.diff; \
|
180
|
|
- touch -r $< $<.diff; \
|
181
|
|
- fi
|
182
|
|
- @rm -f $<.porig
|
183
|
|
- @touch $@
|
|
28
|
+clean:
|
|
29
|
+ rm -f $(GENERATEDPDF)
|
|
30
|
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
31
|
+
|
|
32
|
+latex: Makefile $(GENERATEDPDF)
|
|
33
|
+ cd .. ; python setup.py build ; cd -
|
|
34
|
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
35
|
+
|
|
36
|
+# Catch-all target: route all unknown targets to Sphinx using the new
|
|
37
|
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
38
|
+%: Makefile
|
|
39
|
+ cd .. ; python setup.py build ; cd -
|
|
40
|
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|