blob: 3557ac50596b3b69977a45a996197f5b108ee43c [file] [log] [blame]
# Makefile for Sphinx documentation
# Note, due to a problem with python2/python3 parallel
# installability of sphinx (
# we dont use the standard `sphinx-build` and `sphinx-apidoc` entry points.
# The following technique works as long as sphinx is installed for python3,
# regardless of the entry point which might be in /usr/bin or PATH, but
# will stop working in sphinx >= 2.0. Hopefully by then, the mentioned
# bug will be fixed and we can use a standard python3 specific script to
# invoke sphnix.
SPHINXBUILD = python3 -m sphinx
SPHINXAPIDOC = python3 -m sphinx.apidoc
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
# the i18n builder cannot share the environment and doctrees with the others
# Set BST_FORCE_SESSION_REBUILD to force rebuild the docs
ifneq ($(strip $(BST_FORCE_SESSION_REBUILD)),)
BST2HTMLOPTS = --force
.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean 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 dont 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} -name "*.py" ! -name "_*.py"); do \
base=$$(basename $$file); \
module=${2}.$${}; \
modname=$${}; \
echo -n "Generating source/${2}/$${modname}.rst... "; \
sed -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."; \
# We set PYTHONPATH here because source/ sys.modules hacks dont seem to help sphinx-build import the plugins
all: html devhelp
clean: templates-clean sessions-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.
mkdir -p source/elements
mkdir -p source/sources
$(SPHINXAPIDOC) --force --separate --module-first --no-headings --no-toc -o source $(CURDIR)/../buildstream *_pb2*.py
$(call plugin-doc-skeleton,$(CURDIR)/../buildstream/plugins/elements,elements)
$(call plugin-doc-skeleton,$(CURDIR)/../buildstream/plugins/sources,sources)
rm -rf source/elements
rm -rf source/sources
# Stage the stored sessions into the place where they will
# be used in the build.
# This is separated so that the git tree does not become
# dirty as a result of a documentation build process - which
# messes up the docs version number and the version number
# printed in some command line output.
mkdir -p source/sessions
cp source/sessions-stored/*.html source/sessions
# By default, this will generate the html fragments of colorized BuildStream terminal
# output only if they don't yet exist.
# Specify BST_FORCE_SESSION_REBUILD=1 to force rebuild all session html files.
sessions: sessions-prep
for file in $(wildcard sessions/*.run); do \
$(BST2HTML) $(BST2HTMLOPTS) --description $$file; \
rm -rf source/sessions
# Targets which generate docs with sphinx build
html devhelp: templates sessions
@echo "Building $@..."
PYTHONPATH=$(CURDIR)/../buildstream/plugins \
$(wildcard source/*.rst) \
$(wildcard source/tutorial/*.rst) \
$(wildcard source/examples/*.rst) \
$(wildcard source/elements/*.rst) \
$(wildcard source/sources/*.rst)
@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"