# -*- 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 ?= 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 --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 \ $(BOOKS_FOLDER)/$(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 \ $(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): 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 \ $(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):: $(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 $(MAKE) prepare-gh-pages cd $(GH_PAGES);\ git add --all . ;\ git commit -m "gh-pages: updated" ;\ git push origin gh-pages PHONY += travis-gh-pages travis-gh-pages: $(MAKE) 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)