# -*- coding: utf-8; mode: makefile-gmake -*- export DOCS_FOLDER DOCS_BUILD DOCS_DIST BOOKS_FOLDER BOOKS_DIST # You can set these variables from the command line. SPHINXOPTS ?= SPHINXBUILD ?= $(PY_ENV_BIN)/sphinx-build SPHINX_CONF ?= conf.py DOCS_FOLDER = docs$(LXC_ENV_FOLDER) DOCS_BUILD = build/docs$(LXC_ENV_FOLDER) DOCS_DIST = dist/docs$(LXC_ENV_FOLDER) GH_PAGES ?= gh-pages BOOKS_FOLDER = docs$(LXC_ENV_FOLDER) BOOKS_DIST = dist/books$(LXC_ENV_FOLDER) ifeq ($(KBUILD_VERBOSE),1) SPHINX_VERBOSE = "-v" else SPHINX_VERBOSE = endif ## SPHINXVERS variable ## =================== ## ## .. _requirement-specifiers: https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers ## ## Sphinx version to use, when building documentation. Set this when calling ## build target. The default value is empty (install latest), to select a ## specific version use a requirement-specifiers_. E.g. to build your target ## 'doc' with a select sphinx-doc_ version 1.7.9:: ## ## make SPHINXVERS='==1.7.9' docs ## ## To build with latest 1.7:: ## ## make SPHINXVERS='>=1.7,<1.8' docs ## SPHINXVERS ?= docs-help: @echo 'makefile.sphinx:' @echo ' docs-clean - clean intermediate doc objects' @echo ' $(GH_PAGES) - create & upload github pages' @echo ' sphinx-pdf - run sphinx latex & pdf targets' echo '' @echo ' books/{name}.html : build only the HTML of document {name}' @echo ' valid values for books/{name}.html are:' @echo ' $(BOOKS_HTML)' | $(FMT) @echo ' books/{name}.pdf : build only the PDF of document {name}' @echo ' valid values for books/{name}.pdf are:' @echo ' $(BOOKS_PDF) ' | $(FMT) # ------------------------------------------------------------------------------ # requirements # ------------------------------------------------------------------------------ sphinx-doc: $(PY_ENV) @echo "PYENV installing Sphinx$(SPHINXVERS)" $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)' sphinx-live: $(PY_ENV) @echo "PYENV installing Sphinx$(SPHINXVERS)" $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)' sphinx-autobuild PHONY += msg-texlive texlive ifeq ($(shell which xelatex >/dev/null 2>&1; echo $$?), 1) texlive: msg-TeXLive $(error The 'xelatex' command was not found) else texlive: @: endif msg-texlive: $(Q)echo "\n\ The TeX/PDF output and the *math* extension require TexLive and latexmk:\n\n\ Make sure you have a updated TeXLive with XeTeX engine installed, grab it\n\ it from https://www.tug.org/texlive or install it from your package manager.\n\n\ Install latexmk from your package manager or visit https://ctan.org/pkg/latexmk\n\n\ Sphinx-doc produce (Xe)LaTeX files which might use additional TeX-packages\n\ and fonts. To process these LaTeX files, a TexLive installation with the\n\ additional packages is required. On debian based OS these requirements\n\ are installed by::\n\n\ sudo -H apt-get install\n\ latexmk\n\ texlive-base texlive-xetex texlive-latex-recommended\n\ texlive-extra-utils dvipng ttf-dejavu\n" # ------------------------------------------------------------------------------ # commands # ------------------------------------------------------------------------------ # $2 sphinx builder e.g. "html" # $3 path where configuration file (conf.py) is located # $4 sourcedir # $5 dest subfolder e.g. "man" for man pages at $(DOCS_DIST)/man quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5) cmd_sphinx = SPHINX_CONF=$(abspath $4/$(SPHINX_CONF))\ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5 quiet_cmd_sphinx_autobuild = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5) 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)\ -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5 quiet_cmd_sphinx_clean = CLEAN $@ cmd_sphinx_clean = rm -rf $(DOCS_BUILD) $(DOCS_DIST) $(GH_PAGES)/* $(GH_PAGES)/.buildinfo # ------------------------------------------------------------------------------ # targets # ------------------------------------------------------------------------------ # build PDF of whole documentation in: $(DOCS_DIST)/pdf PHONY += sphinx-pdf sphinx-pdf: sphinx-latex $(Q)cd $(DOCS_BUILD)/latex/; make all-pdf $(Q)mkdir -p $(DOCS_DIST)/pdf $(Q)cp $(DOCS_BUILD)/latex/*.pdf $(DOCS_DIST)/pdf @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)" PHONY += sphinx-latex sphinx-latex: texlive sphinx-doc $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b latex \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/.doctrees \ $(DOCS_FOLDER) \ $(DOCS_BUILD)/latex # Sphinx projects, we call them *books* (what is more common). Books are # folders under $(BOOKS_FOLDER) containing a conf.py file. The HTML output goes # to folder $(BOOKS_DIST)/ while PDF is placed (BOOKS_DIST)//pdf BOOKS=$(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py)) # fine grained targets BOOKS_HTML = $(patsubst %,%.html,$(BOOKS)) BOOKS_CLEAN = $(patsubst %,%.clean,$(BOOKS)) BOOKS_LATEX = $(patsubst %,%.latex,$(BOOKS)) BOOKS_PDF = $(patsubst %,%.pdf,$(BOOKS)) BOOKS_LIVE = $(patsubst %,%.live,$(BOOKS)) $(BOOKS_DIST): mkdir -p $(BOOKS_DIST) PHONY += $(BOOKS_HTML) $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST) SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b html \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \ $(patsubst books/%.html,%,$@) \ $(BOOKS_DIST)/$(patsubst books/%.html,%,$@) @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))" PHONY += $(BOOKS_HTML) $(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST) PATH="$(PY_ENV_BIN):$(PATH)" \ SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \ $(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b html \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \ $(patsubst books/%.live,%,$@) \ $(BOOKS_DIST)/$(patsubst books/%.live,%,$@) $(BOOKS_PDF): %.pdf : %.latex $(Q)cd $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@); make all-pdf $(Q)mkdir -p $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf $(Q)cp -v $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@)/*.pdf $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf" PHONY += $(BOOKS_LATEX) $(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST) SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b latex \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \ $(patsubst books/%.latex,%,$@) \ $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@) @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))" $(BOOKS_CLEAN): $(Q)rm -rf $(BOOKS_DIST)/$(patsubst books/%.clean,%,$@) \ $(DOCS_BUILD)/books/$(patsubst books/%.clean,%,$@) \ $(DOCS_BUILD)/latex/$(patsubst books/%.clean,%,$@) # github pages PHONY += $(GH_PAGES) $(GH_PAGES):: $(MAKE) docs [ -d "gh-pages/.git" ] || git clone $(GIT_URL) gh-pages -cd $(GH_PAGES); git checkout gh-pages >/dev/null -cd $(GH_PAGES); git pull -cd $(GH_PAGES); ls -A | grep -v '.git$$' | xargs rm -rf cp -r $(DOCS_DIST)/* $(GH_PAGES)/ touch $(GH_PAGES)/.nojekyll echo "" > $(GH_PAGES)/404.html cd $(GH_PAGES);\ git add --all . ;\ git commit -m "gh-pages: updated" ;\ git push origin gh-pages PHONY += docs-clean docs-clean: $(BOOKS_CLEAN) $(call cmd,sphinx_clean) .PHONY: $(PHONY)