build: non-recursive doc + parallel sphinx

Sphinx actually does work with a parallel build, if the doctree creation
is a separate step (which the other builds will then just read
unmodified.)  This can be done with the "dummy" target.

This also adds "-j6" to sphinx-build and adds a "--disable-doc-html"
switch on ./configure to turn on/off building HTML docs separately.

Also, HTML docs are now installed by "make install" to
/usr/share/doc/frr/html.

Signed-off-by: David Lamparter <equinox@diac24.net>

1 files changed, 176 insertions, 0 deletions

diff --git a/doc/subdir.am b/doc/subdir.am
new file mode 100644
index 0000000000..4170101655
--- /dev/null
+++ b/doc/subdir.am
@@ -0,0 +1,176 @@
+#
+# doc
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+PAPER         ?=
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
+
+###
+
+AM_V_SPHINX = $(am__v_SPHINX_$(V))
+am__v_SPHINX_ = $(am__v_SPHINX_$(AM_DEFAULT_VERBOSITY))
+am__v_SPHINX_0 = @echo "  SPHINX  " $@;
+am__v_SPHINX_1 =
+AM_V_MAKEINFO = $(am__v_MAKEINFO_$(V))
+am__v_MAKEINFO_ = $(am__v_MAKEINFO_$(AM_DEFAULT_VERBOSITY))
+am__v_MAKEINFO_0 = @echo "  MAKEINFO" $@;
+am__v_MAKEINFO_1 =
+
+#
+# real-file sphinx targets that work for dependencies
+#
+
+doc/%/_build/.doctrees/environment.pickle:
+	$(AM_V_SPHINX) ( \
+		subdoc="$@"; subdoc="$${subdoc#doc/}"; subdoc="doc/$${subdoc%%/*}"; \
+		$(SPHINXBUILD) -a -q -b text -d "$${subdoc}/_build/.doctrees" \
+			$(ALLSPHINXOPTS) "$(top_srcdir)/$${subdoc}" "$${subdoc}/_build/text" \
+	)
+doc/%/_build/html/.buildinfo: doc/%/_build/.doctrees/environment.pickle
+	$(AM_V_SPHINX) ( \
+		subdoc="$@"; subdoc="$${subdoc#doc/}"; subdoc="doc/$${subdoc%%/*}"; \
+		$(SPHINXBUILD) -q -b html -d "$${subdoc}/_build/.doctrees" \
+			$(ALLSPHINXOPTS) "$(top_srcdir)/$${subdoc}" "$${subdoc}/_build/html" \
+	)
+.PRECIOUS: doc/%/_build/texinfo/frr.texi
+doc/%/_build/texinfo/frr.texi: doc/%/_build/.doctrees/environment.pickle
+	$(AM_V_SPHINX) ( \
+		subdoc="$@"; subdoc="$${subdoc#doc/}"; subdoc="doc/$${subdoc%%/*}"; \
+		$(SPHINXBUILD) -q -b texinfo -d "$${subdoc}/_build/.doctrees" \
+			$(ALLSPHINXOPTS) "$(top_srcdir)/$${subdoc}" "$${subdoc}/_build/texinfo" \
+	)
+doc/%/_build/texinfo/frr.info: doc/%/_build/texinfo/frr.texi
+	$(AM_V_MAKEINFO)$(MAKEINFO) --no-split -o '$@' '$<'
+doc/%/_build/man/man.stamp: doc/%/_build/.doctrees/environment.pickle
+	$(AM_V_SPHINX) ( \
+		subdoc="$@"; subdoc="$${subdoc#doc/}"; subdoc="doc/$${subdoc%%/*}"; \
+		$(MKDIR_P) "$${subdoc}/_build/man"; touch $@.tmp; \
+		$(SPHINXBUILD) -a -q -b man -d "$${subdoc}/_build/.doctrees" \
+			$(ALLSPHINXOPTS) "$(top_srcdir)/$${subdoc}" "$${subdoc}/_build/man" && \
+			mv $@.tmp $@ \
+	)
+
+#
+# auxiliary sphinx targets (output name = directory,
+# deps will not work very well)
+#
+
+SPHINXTARGETS = \
+	  html dirhtml singlehtml pickle json \
+	  htmlhelp qthelp applehelp devhelp \
+	  epub latex text man texinfo gettext \
+	  changes linkcheck doctest coverage \
+	  xml pseudoxml \
+	  # end
+
+M_SPHINXTARGETS = $(addprefix doc/%/_build/,$(SPHINXTARGETS))
+.PRECIOUS: $(M_SPHINXTARGETS)
+$(M_SPHINXTARGETS): doc/%/_build/.doctrees/environment.pickle
+	$(AM_V_SPHINX) ( \
+		target="$@"; \
+		builder="$${target##*/}"; \
+		subdoc="$${target#doc/}"; subdoc="doc/$${subdoc%%/*}"; \
+		rm -rf "$@"; \
+		$(SPHINXBUILD) -q -b $${builder} -d $${subdoc}/_build/.doctrees \
+			$(ALLSPHINXOPTS) $(top_srcdir)/$${subdoc} $@ \
+	)
+
+.PHONY: doc/%/_build/latexpdf
+doc/%/_build/latexpdf: doc/%/_build/latex
+	@make -C $< all-pdf
+
+# If you want to build the developer's docs in other formats, try the
+# following:
+#
+# $ cd developer
+# $ make help
+
+# dist tarballs want doc sources
+EXTRA_DIST += \
+	doc/mpls/ChangeLog.opaque.txt \
+	doc/mpls/ospfd.conf \
+	doc/mpls/cli_summary.txt \
+	doc/mpls/opaque_lsa.txt \
+	doc/figures/cligraph.png \
+	doc/figures/cligraph.svg \
+	doc/figures/fig-normal-processing.dia \
+	doc/figures/fig-normal-processing.png \
+	doc/figures/fig-normal-processing.txt \
+	doc/figures/fig-rs-processing.dia \
+	doc/figures/fig-rs-processing.png \
+	doc/figures/fig-rs-processing.txt \
+	doc/figures/fig_topologies_full.dia \
+	doc/figures/fig_topologies_full.png \
+	doc/figures/fig_topologies_full.txt \
+	doc/figures/fig_topologies_rs.dia \
+	doc/figures/fig_topologies_rs.png \
+	doc/figures/fig_topologies_rs.txt \
+	doc/figures/fig-vnc-commercial-route-reflector.dia \
+	doc/figures/fig-vnc-commercial-route-reflector.png \
+	doc/figures/fig-vnc-commercial-route-reflector.txt \
+	doc/figures/fig-vnc-frr-route-reflector.dia \
+	doc/figures/fig-vnc-frr-route-reflector.png \
+	doc/figures/fig-vnc-frr-route-reflector.txt \
+	doc/figures/fig-vnc-gw.dia \
+	doc/figures/fig-vnc-gw.png \
+	doc/figures/fig-vnc-gw-rr.dia \
+	doc/figures/fig-vnc-gw-rr.png \
+	doc/figures/fig-vnc-gw-rr.txt \
+	doc/figures/fig-vnc-gw.txt \
+	doc/figures/fig-vnc-mesh.dia \
+	doc/figures/fig-vnc-mesh.png \
+	doc/figures/fig-vnc-mesh.txt \
+	doc/figures/fig-vnc-redundant-route-reflectors.dia \
+	doc/figures/fig-vnc-redundant-route-reflectors.png \
+	doc/figures/fig-vnc-redundant-route-reflectors.txt \
+	doc/figures/frr-icon.svg \
+	doc/figures/frr-logo-icon.png \
+	doc/figures/frr-logo-medium.png \
+	doc/figures/frr-logo.png \
+	doc/figures/frr-logo-small.png \
+	doc/figures/git_branches.png \
+	doc/figures/git_branches.svg \
+	doc/figures/ospf_api_architecture.png \
+	doc/figures/ospf_api_msghdr.png \
+	doc/figures/ospf_api_msgs1.png \
+	doc/figures/ospf_api_msgs2.png \
+	doc/extra/frrlexer.py \
+	# end
+
+
+.PHONY: doc/help
+doc/help:
+	@echo "Please use \`make doc/{user,manpages,developer}/<target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"