doc/Makefile

#
#  Copyright (C) 2018 Codethink Limited
#  Copyright (C) 2018 Bloomberg Finance LP
#
#  This program is free software; you can redistribute it and/or
#  modify it under the terms of the GNU Lesser General Public
#  License as published by the Free Software Foundation; either
#  version 2 of the License, or (at your option) any later version.
#
#  This library is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
#  Lesser General Public License for more details.
#
#  You should have received a copy of the GNU Lesser General Public
#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
#
#  Authors:
#        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
#        William Salmon <will.salmon@codethink.co.uk>

# Makefile for Sphinx documentation
#

# Note, due to a problem with python2/python3 parallel
# installability of sphinx (https://github.com/sphinx-doc/sphinx/issues/4375)
# 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.
#
SPHINXOPTS    =
SPHINXBUILD   = python3 -m sphinx
SPHINXAPIDOC  = python3 -m sphinx.apidoc
PAPER         =
BUILDDIR      = build

# Internal variables.
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -W -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

# Set BST_FORCE_SESSION_REBUILD to force rebuild the docs
BST2HTML = $(CURDIR)/bst2html.py
BST2HTMLOPTS =
ifneq ($(strip $(BST_FORCE_SESSION_REBUILD)),)
BST2HTMLOPTS = --force
endif
ifneq ($(strip $(BST_DUMMY_REBUILD)),)
BST2HTMLOPTS += --dummy
endif

# Help Python find buildstream and its plugins
PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins


.PHONY: all clean templates templates-clean sessions sessions-prep sessions-clean badges badges-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}.$${base%.py};					\
	    modname=$${base%.py};					\
	    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."; \
	done
endef


all: html devhelp

clean: templates-clean sessions-clean badges-clean
	rm -rf build

############################################################
#                 Plugin doc templates                     #
############################################################

# 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
	$(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)

templates-clean:
	rm -rf source/elements
	rm -rf source/sources

############################################################
#                   Session captures                       #
############################################################

# 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		\
	    PYTHONPATH=$(PYTHONPATH) $(BST2HTML) $(BST2HTMLOPTS) $$file;	\
	done

sessions-clean:
	rm -rf source/sessions


############################################################
#                  Generate release badges                 #
############################################################
badges-clean:
	rm -rf source/badges

badges:
	mkdir -p source/badges
	$(CURDIR)/badges.py > source/badges/snapshot.svg
	$(CURDIR)/badges.py --release > source/badges/release.svg


############################################################
#                    Main sphinx build                     #
############################################################

# Targets which generate docs with sphinx build
#
#
html devhelp: templates sessions badges
	@echo "Building $@..."
	PYTHONPATH=$(PYTHONPATH) \
	    $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) "$(BUILDDIR)/$@" \
	    $(wildcard source/*.rst) \
	    $(wildcard source/tutorial/*.rst) \
            $(wildcard source/advanced-features/*.rst) \
	    $(wildcard source/examples/*.rst) \
	    $(wildcard source/elements/*.rst) \
	    $(wildcard source/sources/*.rst) \
	    $(wildcard source/developing/*.rst)
	@echo
	@echo "Build of $@ finished, output: $(CURDIR)/$(BUILDDIR)/$@"
# Makefile for Sphinx documentation
#