@@ -0,0 +1,215 @@
1+# -*- coding: utf-8; mode: makefile-gmake -*-
2+
3+# You can set these variables from the command line.
4+SPHINXOPTS ?=
5+SPHINXBUILD ?= $(PY_ENV_BIN)/sphinx-build
6+SPHINX_CONF ?= conf.py
7+
8+DOCS_FOLDER ?= docs
9+DOCS_BUILD ?= build/docs
10+DOCS_DIST ?= dist/docs
11+GH_PAGES ?= gh-pages
12+
13+BOOKS_FOLDER ?= docs
14+BOOKS_DIST ?= dist/books
15+
16+ifeq ($(KBUILD_VERBOSE),1)
17+ SPHINX_VERBOSE = "-v"
18+else
19+ SPHINX_VERBOSE =
20+endif
21+
22+## SPHINXVERS variable
23+## ===================
24+##
25+## .. _requirement-specifiers: https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers
26+##
27+## Sphinx version to use, when building documentation. Set this when calling
28+## build target. The default value is empty (install latest), to select a
29+## specific version use a requirement-specifiers_. E.g. to build your target
30+## 'doc' with a select sphinx-doc_ version 1.7.9::
31+##
32+## make SPHINXVERS='==1.7.9' docs
33+##
34+## To build with latest 1.7::
35+##
36+## make SPHINXVERS='>=1.7,<1.8' docs
37+##
38+SPHINXVERS ?=
39+
40+docs-help:
41+ @echo 'makefile.sphinx:'
42+ @echo ' docs-clean - clean intermediate doc objects'
43+ @echo ' $(GH_PAGES) - create & upload github pages'
44+ @echo ' sphinx-pdf - run sphinx latex & pdf targets'
45+ echo ''
46+ @echo ' books/{name}.html : build only the HTML of document {name}'
47+ @echo ' valid values for books/{name}.html are:'
48+ @echo ' $(BOOKS_HTML)' | $(FMT)
49+ @echo ' books/{name}.pdf : build only the PDF of document {name}'
50+ @echo ' valid values for books/{name}.pdf are:'
51+ @echo ' $(BOOKS_PDF) ' | $(FMT)
52+
53+# ------------------------------------------------------------------------------
54+# requirements
55+# ------------------------------------------------------------------------------
56+
57+sphinx-doc: $(PY_ENV)
58+ @echo "PYENV installing Sphinx$(SPHINXVERS)"
59+ $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)'
60+
61+sphinx-live: $(PY_ENV)
62+ @echo "PYENV installing Sphinx$(SPHINXVERS)"
63+ $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)' sphinx-autobuild
64+
65+
66+PHONY += msg-texlive texlive
67+
68+ifeq ($(shell which xelatex >/dev/null 2>&1; echo $$?), 1)
69+texlive: msg-TeXLive
70+ $(error The 'xelatex' command was not found)
71+else
72+texlive:
73+ @:
74+endif
75+
76+msg-texlive:
77+ $(Q)echo "\n\
78+The TeX/PDF output and the *math* extension require TexLive and latexmk:\n\n\
79+ Make sure you have a updated TeXLive with XeTeX engine installed, grab it\n\
80+ it from https://www.tug.org/texlive or install it from your package manager.\n\n\
81+ Install latexmk from your package manager or visit https://ctan.org/pkg/latexmk\n\n\
82+ Sphinx-doc produce (Xe)LaTeX files which might use additional TeX-packages\n\
83+ and fonts. To process these LaTeX files, a TexLive installation with the\n\
84+ additional packages is required. On debian based OS these requirements\n\
85+ are installed by::\n\n\
86+ sudo -H apt-get install\n\
87+ latexmk\n\
88+ texlive-base texlive-xetex texlive-latex-recommended\n\
89+ texlive-extra-utils dvipng ttf-dejavu\n"
90+
91+# ------------------------------------------------------------------------------
92+# commands
93+# ------------------------------------------------------------------------------
94+
95+# $2 sphinx builder e.g. "html"
96+# $3 path where configuration file (conf.py) is located
97+# $4 sourcedir
98+# $5 dest subfolder e.g. "man" for man pages at $(DOCS_DIST)/man
99+
100+quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
101+ cmd_sphinx = SPHINX_CONF=$(abspath $4/$(SPHINX_CONF))\
102+ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
103+ -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
104+
105+quiet_cmd_sphinx_autobuild = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
106+ cmd_sphinx_autobuild = PATH="$(PY_ENV_BIN):$(PATH)" $(PY_ENV_BIN)/sphinx-autobuild $(SPHINX_VERBOSE) --poll -B --host 0.0.0.0 --port 8080 $(SPHINXOPTS)\
107+ -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
108+
109+quiet_cmd_sphinx_clean = CLEAN $@
110+ cmd_sphinx_clean = rm -rf $(DOCS_BUILD) $(DOCS_DIST) $(GH_PAGES)/* $(GH_PAGES)/.buildinfo
111+
112+# ------------------------------------------------------------------------------
113+# targets
114+# ------------------------------------------------------------------------------
115+
116+# build PDF of whole documentation in: $(DOCS_DIST)/pdf
117+
118+PHONY += sphinx-pdf
119+sphinx-pdf: sphinx-latex
120+ $(Q)cd $(DOCS_BUILD)/latex/; make all-pdf
121+ $(Q)mkdir -p $(DOCS_DIST)/pdf
122+ $(Q)cp $(DOCS_BUILD)/latex/*.pdf $(DOCS_DIST)/pdf
123+ @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)"
124+
125+PHONY += sphinx-latex
126+sphinx-latex: texlive sphinx-doc
127+ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
128+ -b latex \
129+ -c $(DOCS_FOLDER) \
130+ -d $(DOCS_BUILD)/.doctrees \
131+ $(DOCS_FOLDER) \
132+ $(DOCS_BUILD)/latex
133+
134+# Sphinx projects, we call them *books* (what is more common). Books are
135+# folders under $(BOOKS_FOLDER) containing a conf.py file. The HTML output goes
136+# to folder $(BOOKS_DIST)/<name> while PDF is placed (BOOKS_DIST)/<name>/pdf
137+
138+BOOKS=$(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py))
139+
140+# fine grained targets
141+BOOKS_HTML = $(patsubst %,%.html,$(BOOKS))
142+BOOKS_CLEAN = $(patsubst %,%.clean,$(BOOKS))
143+BOOKS_LATEX = $(patsubst %,%.latex,$(BOOKS))
144+BOOKS_PDF = $(patsubst %,%.pdf,$(BOOKS))
145+BOOKS_LIVE = $(patsubst %,%.live,$(BOOKS))
146+
147+$(BOOKS_DIST):
148+ mkdir -p $(BOOKS_DIST)
149+
150+PHONY += $(BOOKS_HTML)
151+$(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
152+ SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \
153+ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
154+ -b html \
155+ -c $(DOCS_FOLDER) \
156+ -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \
157+ $(patsubst books/%.html,%,$@) \
158+ $(BOOKS_DIST)/$(patsubst books/%.html,%,$@)
159+ @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
160+
161+PHONY += $(BOOKS_HTML)
162+$(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST)
163+ PATH="$(PY_ENV_BIN):$(PATH)" \
164+ SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \
165+ $(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\
166+ -b html \
167+ -c $(DOCS_FOLDER) \
168+ -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \
169+ $(patsubst books/%.live,%,$@) \
170+ $(BOOKS_DIST)/$(patsubst books/%.live,%,$@)
171+
172+$(BOOKS_PDF): %.pdf : %.latex
173+ $(Q)cd $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@); make all-pdf
174+ $(Q)mkdir -p $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
175+ $(Q)cp -v $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@)/*.pdf $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
176+ @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf"
177+
178+PHONY += $(BOOKS_LATEX)
179+$(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST)
180+ SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \
181+ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
182+ -b latex \
183+ -c $(DOCS_FOLDER) \
184+ -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \
185+ $(patsubst books/%.latex,%,$@) \
186+ $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@)
187+ @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))"
188+
189+$(BOOKS_CLEAN):
190+ $(Q)rm -rf $(BOOKS_DIST)/$(patsubst books/%.clean,%,$@) \
191+ $(DOCS_BUILD)/books/$(patsubst books/%.clean,%,$@) \
192+ $(DOCS_BUILD)/latex/$(patsubst books/%.clean,%,$@)
193+
194+# github pages
195+
196+PHONY += $(GH_PAGES)
197+$(GH_PAGES):
198+ $(MAKE) docs
199+ [ -d "gh-pages/.git" ] || git clone $(GIT_URL) gh-pages
200+ -cd $(GH_PAGES); git checkout --orphan gh-pages || exit 0
201+ rm -rf $(GH_PAGES)/* $(GH_PAGES)/.gitignore
202+ touch $(GH_PAGES)/.nojekyll ;\
203+ cp -r $(DOCS_DIST)/* $(GH_PAGES)/
204+ echo "<html><head><META http-equiv='refresh' content='0;URL=index.html'></head></html>" > $(GH_PAGES)/404.html
205+ -cd $(GH_PAGES); git push origin :gh-pages
206+ cd $(GH_PAGES);\
207+ git add --all . ;\
208+ git commit -m "gh-pages: updated" ;\
209+ git push origin gh-pages
210+
211+PHONY += docs-clean
212+docs-clean: $(BOOKS_CLEAN)
213+ $(call cmd,sphinx_clean)
214+
215+.PHONY: $(PHONY)