Makefile 8.54 KB
Newer Older
Nelso Jost's avatar
Nelso Jost committed
1
# Makefile for Sphinx documentation
2
3
4
5
#
PYBIN := python3
VENVDIR := $(shell pwd)/.venv
VENVPY := ${VENVDIR}/bin/python
6
 
Nelso Jost's avatar
Nelso Jost committed
7
8
# You can set these variables from the command line.
SPHINXOPTS    =
9
SPHINXBUILD   = ${VENVDIR}/bin/sphinx-build
Nelso Jost's avatar
Nelso Jost committed
10
11
12
13
14
15
16
17
18
19
PAPER         =
BUILDDIR      = _build

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

20
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext setup
Nelso Jost's avatar
Nelso Jost committed
21

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

clean:
	rm -rf $(BUILDDIR)/*

52
html: check-venv
Nelso Jost's avatar
Nelso Jost committed
53
54
55
56
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

57
dirhtml: check-venv
Nelso Jost's avatar
Nelso Jost committed
58
59
60
61
	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

62
singlehtml: check-venv
Nelso Jost's avatar
Nelso Jost committed
63
64
65
66
	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
	@echo
	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

67
pickle: check-venv
Nelso Jost's avatar
Nelso Jost committed
68
69
70
71
	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
	@echo
	@echo "Build finished; now you can process the pickle files."

72
json: check-venv
Nelso Jost's avatar
Nelso Jost committed
73
74
75
76
	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
	@echo
	@echo "Build finished; now you can process the JSON files."

77
htmlhelp: check-venv
Nelso Jost's avatar
Nelso Jost committed
78
79
80
81
82
	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
	@echo
	@echo "Build finished; now you can run HTML Help Workshop with the" \
	      ".hhp project file in $(BUILDDIR)/htmlhelp."

83
qthelp: check-venv
Nelso Jost's avatar
Nelso Jost committed
84
85
86
87
88
89
90
91
	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
	@echo
	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/arduino-meteorolog.qhcp"
	@echo "To view the help file:"
	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/arduino-meteorolog.qhc"

92
applehelp: check-venv
Nelso Jost's avatar
Nelso Jost committed
93
94
95
96
97
98
99
	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
	@echo
	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
	@echo "N.B. You won't be able to view it unless you put it in" \
	      "~/Library/Documentation/Help or install it in your application" \
	      "bundle."

100
devhelp: check-venv
Nelso Jost's avatar
Nelso Jost committed
101
102
103
104
105
106
107
108
	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
	@echo
	@echo "Build finished."
	@echo "To view the help file:"
	@echo "# mkdir -p $$HOME/.local/share/devhelp/arduino-meteorolog"
	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/arduino-meteorolog"
	@echo "# devhelp"

109
epub: check-venv
Nelso Jost's avatar
Nelso Jost committed
110
111
112
113
	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
	@echo
	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

114
latex: check-venv
Nelso Jost's avatar
Nelso Jost committed
115
116
117
118
119
120
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
	@echo
	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
	@echo "Run \`make' in that directory to run these through (pdf)latex" \
	      "(use \`make latexpdf' here to do that automatically)."

121
latexpdf: check-venv
Nelso Jost's avatar
Nelso Jost committed
122
123
124
125
126
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
	@echo "Running LaTeX files through pdflatex..."
	$(MAKE) -C $(BUILDDIR)/latex all-pdf
	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

127
latexpdfja: check-venv
Nelso Jost's avatar
Nelso Jost committed
128
129
130
131
132
	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
	@echo "Running LaTeX files through platex and dvipdfmx..."
	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

133
text: check-venv
Nelso Jost's avatar
Nelso Jost committed
134
135
136
137
	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
	@echo
	@echo "Build finished. The text files are in $(BUILDDIR)/text."

138
man: check-venv
Nelso Jost's avatar
Nelso Jost committed
139
140
141
142
	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
	@echo
	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

143
texinfo: check-venv
Nelso Jost's avatar
Nelso Jost committed
144
145
146
147
148
149
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
	@echo
	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
	@echo "Run \`make' in that directory to run these through makeinfo" \
	      "(use \`make info' here to do that automatically)."

150
info: check-venv
Nelso Jost's avatar
Nelso Jost committed
151
152
153
154
155
	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
	@echo "Running Texinfo files through makeinfo..."
	make -C $(BUILDDIR)/texinfo info
	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

156
gettext: check-venv
Nelso Jost's avatar
Nelso Jost committed
157
158
159
160
	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
	@echo
	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

161
changes: check-venv
Nelso Jost's avatar
Nelso Jost committed
162
163
164
165
	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
	@echo
	@echo "The overview file is in $(BUILDDIR)/changes."

166
linkcheck: check-venv
Nelso Jost's avatar
Nelso Jost committed
167
168
169
170
171
	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
	@echo
	@echo "Link check complete; look for any errors in the above output " \
	      "or in $(BUILDDIR)/linkcheck/output.txt."

172
doctest: check-venv
Nelso Jost's avatar
Nelso Jost committed
173
174
175
176
	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
	@echo "Testing of doctests in the sources finished, look at the " \
	      "results in $(BUILDDIR)/doctest/output.txt."

177
coverage: check-venv
Nelso Jost's avatar
Nelso Jost committed
178
179
180
181
	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
	@echo "Testing of coverage in the sources finished, look at the " \
	      "results in $(BUILDDIR)/coverage/python.txt."

182
xml: check-venv
Nelso Jost's avatar
Nelso Jost committed
183
184
185
186
	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
	@echo
	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."

187
pseudoxml: check-venv
Nelso Jost's avatar
Nelso Jost committed
188
189
190
	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
	@echo
	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218

setup: clean-venv create-venv

create-venv:
	@ echo "-------------------------------------------------------"
	virtualenv -v --python='${PYBIN}' ${VENVDIR} --no-site-packages
	${VENVDIR}/bin/pip install --upgrade pip
	${VENVDIR}/bin/pip install -r requirements.pip
	@ echo "-------------------------------------------------------"
	@ echo "Required Python virtual environment installed at "
	@ du -sh ${VENVDIR}

clean-venv:
	rm -rf ${VENVDIR}

check-venv:
	@ command -v ${VENVPY} >/dev/null 2>&1 || \
		{ printf "You need to prepare the required Python virtual environment";\
		  printf "\nfor running this software. Excecute, just once:";\
		  printf "\n\n    $$ make setup\n\nor\n\n    ";\
	   	  printf "$$ make setup PYBIN=<python_binary>\n\nfor specifying a ";\
		  printf "Python binary other than 'python3', like\n'python-3.x' ";\
		  printf "(where x is a number) for instance. \n\n"; exit 1; }

# User-friendly check for sphinx-build
# ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
# $(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/")
# endif