| # Makefile for Sphinx documentation |
| # |
| |
| # You can set these variables from the command line. |
| SPHINXOPTS = -W |
| SPHINXBUILD = sphinx-build |
| 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) source |
| # the i18n builder cannot share the environment and doctrees with the others |
| I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source |
| |
| # Fix for when python is mapped to python2 not python3 |
| # This is an issue in the sphinx-build script provided in the default install |
| # because it uses the generic python env, so we need to have a copy of this script |
| # but with an explicit call to python3. |
| # |
| # Why python3? We are using some features of sphinx that are only implemented |
| # currently in python3 |
| # |
| PYV=$(shell python -c "import sys;t='{v[0]}'.format(v=list(sys.version_info[:2]));sys.stdout.write(t)") |
| |
| ifeq ($(PYV), 2) |
| SPHINXBUILD = ./sphinx-build3 |
| endif |
| |
| .PHONY: all clean templates html devhelp |
| |
| # Canned recipe for generating plugin api skeletons |
| # $1 = the plugin directory |
| # $2 = the output docs directory |
| # |
| # Explanation: |
| # |
| # Sphinx does not have any option for skipping documentation, |
| # we don't want to document plugin code because nobody uses that |
| # but we do want to use module-level docstrings in plugins in |
| # order to explain how plugins work. |
| # |
| # For this purpose, we replace sphinx-apidoc with a simple |
| # makefile rule which generates a template slightly differently |
| # from how sphinx does it, allowing us to get what we want |
| # from plugin documentation. |
| # |
| define plugin-doc-skeleton |
| @for file in $$(find ${1}/${2} -name "*.py" ! -name "_*"); do \ |
| base=$$(basename $$file); \ |
| module=${2}.$${base%.py}; \ |
| modname=$${base%.py}; \ |
| echo -n "Generating source/${2}/$${modname}.rst... "; \ |
| sed -e "s|@@MODULENAME@@|$${modname}|g" \ |
| -e "s|@@MODULE@@|$${module}|g" \ |
| source/plugin.rsttemplate > \ |
| source/${2}/$${modname}.rst.tmp && \ |
| mv source/${2}/$${modname}.rst.tmp source/${2}/$${modname}.rst || exit 1; \ |
| echo "Done."; \ |
| done |
| endef |
| |
| # We set PYTHONPATH here because source/conf.py sys.modules hacks don't seem to help sphinx-build import the plugins |
| all: html devhelp |
| |
| clean: templates-clean |
| rm -rf build |
| |
| # Generate rst templates for the docs using a mix of sphinx-apidoc and |
| # our 'plugin-doc-skeleton' routine for plugin pages. |
| templates: |
| mkdir -p source/elements |
| mkdir -p source/sources |
| $(call plugin-doc-skeleton,$(CURDIR)/../src/buildstream_plugins,elements) |
| $(call plugin-doc-skeleton,$(CURDIR)/../src/buildstream_plugins,sources) |
| |
| templates-clean: |
| rm -rf source/elements |
| rm -rf source/sources |
| |
| # Targets which generate docs with sphinx build |
| # |
| # |
| html devhelp: templates |
| @echo "Building $@..." |
| PYTHONPATH=$(CURDIR)/../src/buildstream_plugins \ |
| $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \ |
| $(wildcard source/*.rst) \ |
| $(wildcard source/elements/*.rst) \ |
| $(wildcard source/sources/*.rst) |
| @echo |
| @echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@" |
| |
| testy: |
| @echo "Using $(SPHINXBUILD)" |
| @echo "Py is $(PYV)" |