# -*- 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 DOCS_BUILD = ./$(LXC_ENV_FOLDER)build/docs DOCS_DIST = ./$(LXC_ENV_FOLDER)dist/docs GH_PAGES ?= build/gh-pages BOOKS_FOLDER = ./docs BOOKS_DIST = ./$(LXC_ENV_FOLDER)dist/books ifeq ($(KBUILD_VERBOSE),1) SPHINX_VERBOSE = "-v" else SPHINX_VERBOSE = endif 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 # ------------------------------------------------------------------------------ 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) --open-browser --host 0.0.0.0 $(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: pyenvinstall texlive $(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): pyenvinstall | $(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 \ $(BOOKS_FOLDER)/$(patsubst books/%.html,%,$@) \ $(BOOKS_DIST)/$(patsubst books/%.html,%,$@) @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))" PHONY += $(BOOKS_HTML) $(BOOKS_LIVE): pyenvinstall | $(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 \ $(BOOKS_FOLDER)/$(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): pyenvinstall | $(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 \ $(BOOKS_FOLDER)/$(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 += prepare-gh-pages prepare-gh-pages: cp -r $(DOCS_DIST)/* $(GH_PAGES)/ touch $(GH_PAGES)/.nojekyll echo "" > $(GH_PAGES)/404.html PHONY += gh-pages gh-pages: docs-clean docs - git worktree remove -f $(GH_PAGES) || exit 0 - git branch -D gh-pages || exit 0 git worktree add --no-checkout $(GH_PAGES) master cd $(GH_PAGES); git checkout --orphan gh-pages && git rm -rfq . $(MAKE) prepare-gh-pages cd $(GH_PAGES);\ git add --all . ;\ git commit -q -m "make gh-pages: from $(shell git config --get remote.origin.url)@$(shell git rev-parse HEAD)" ;\ git push -f origin gh-pages PHONY += ci-gh-pages ci-gh-pages: docs-clean docs rm -Rf $(GH_PAGES) mkdir -p $(GH_PAGES) $(MAKE) prepare-gh-pages PHONY += docs-clean docs-clean: $(BOOKS_CLEAN) $(call cmd,sphinx_clean) .PHONY: $(PHONY)