From 1d3a49230933e25a5a21a81622f2cc152ee7bc4d Mon Sep 17 00:00:00 2001 From: Quentin Young Date: Wed, 2 May 2018 14:42:28 -0400 Subject: [PATCH] doc: support VPATH builds Documentation was not fully using Automake / Autoconf and therefore needs modifications to support black magic VPATH builds. * Convert Makefile's to Autoconf-controlled Makefile.in's * Tweak loading of pygments lexer to handle runtime paths * Update .gitignore's as necessary Signed-off-by: Quentin Young --- configure.ac | 9 +++++++-- doc/Makefile.am | 2 +- doc/developer/.gitignore | 2 +- doc/developer/Makefile | 1 - doc/developer/Makefile.in | 8 ++++++++ doc/developer/conf.py | 10 +++++++++- doc/frr-sphinx.mk | 9 +++++++-- doc/manpages/.gitignore | 2 +- doc/manpages/{Makefile => Makefile.in} | 9 ++++++++- doc/user/.gitignore | 2 +- doc/user/{Makefile => Makefile.in} | 9 ++++++++- doc/user/conf.py | 10 +++++++++- 12 files changed, 60 insertions(+), 13 deletions(-) delete mode 100644 doc/developer/Makefile create mode 100644 doc/developer/Makefile.in rename doc/manpages/{Makefile => Makefile.in} (84%) rename doc/user/{Makefile => Makefile.in} (87%) diff --git a/configure.ac b/configure.ac index 0be0a5b16d..689397e794 100755 --- a/configure.ac +++ b/configure.ac @@ -1913,8 +1913,13 @@ AC_MSG_RESULT($ac_cv_htonl_works) AC_CONFIG_FILES([Makefile bgpd/Makefile vtysh/Makefile - doc/Makefile tests/Makefile - bgpd/rfp-example/rfptest/Makefile bgpd/rfp-example/librfp/Makefile + doc/Makefile + doc/user/Makefile + doc/manpages/Makefile + doc/developer/Makefile + tests/Makefile + bgpd/rfp-example/rfptest/Makefile + bgpd/rfp-example/librfp/Makefile redhat/frr.spec debianpkg/Makefile debianpkg/changelog diff --git a/doc/Makefile.am b/doc/Makefile.am index 053842283e..8fa057424a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,7 +14,7 @@ .NOTPARALLEL: SUBDIRS = manpages user -AM_MAKEFLAGS = DESTDIR=${DESTDIR} infodir=${infodir} doczdir=${abs_srcdir} +AM_MAKEFLAGS = DESTDIR=${DESTDIR} infodir=${infodir} MANPAGE_BUILDDIR = manpages/_build/man diff --git a/doc/developer/.gitignore b/doc/developer/.gitignore index 0505537159..2e7d8573f1 100644 --- a/doc/developer/.gitignore +++ b/doc/developer/.gitignore @@ -1,3 +1,3 @@ /_templates /_build -!/Makefile +!/Makefile.in diff --git a/doc/developer/Makefile b/doc/developer/Makefile deleted file mode 100644 index 9807a750bf..0000000000 --- a/doc/developer/Makefile +++ /dev/null @@ -1 +0,0 @@ -include ../frr-sphinx.mk diff --git a/doc/developer/Makefile.in b/doc/developer/Makefile.in new file mode 100644 index 0000000000..76758f9242 --- /dev/null +++ b/doc/developer/Makefile.in @@ -0,0 +1,8 @@ +# This is necessary to support VPATH builds. +srcdir = @srcdir@ +VPATH = @srcdir@ + +# This variable is used as the documentation source location in frr-sphinx.mk +SOURCESDIR = @srcdir@ + +include @srcdir@/../frr-sphinx.mk diff --git a/doc/developer/conf.py b/doc/developer/conf.py index a3968b60ff..61253c4b2f 100644 --- a/doc/developer/conf.py +++ b/doc/developer/conf.py @@ -342,6 +342,14 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False +# contents of ../extra/frrlexer.py. +# This is read here to support VPATH build. Since this section is execfile()'d +# with the file location, we can safely use a relative path here to save the +# contents of the lexer file for later use even if our relative path changes +# due to VPATH. +with open('../extra/frrlexer.py', 'rb') as lex: + frrlexerpy = lex.read() + # custom extensions here def setup(app): # object type for FRR CLI commands, can be extended to document parent CLI @@ -357,5 +365,5 @@ def setup(app): # # frrlexer = pygments.lexers.load_lexer_from_file('../extra/frrlexer.py', lexername="FRRLexer") custom_namespace = {} - exec(open('../extra/frrlexer.py', 'rb').read(), custom_namespace) + exec(frrlexerpy, custom_namespace) lexers['frr'] = custom_namespace['FRRLexer']() diff --git a/doc/frr-sphinx.mk b/doc/frr-sphinx.mk index df4056760d..3e4c67d374 100644 --- a/doc/frr-sphinx.mk +++ b/doc/frr-sphinx.mk @@ -10,6 +10,11 @@ SPHINXBUILD ?= sphinx-build PAPER ?= BUILDDIR = _build +# This is a custom FRR variable just for this docs subdirectory used to support +# VPATH builds. Makefiles which include this file should override it to point +# to the correct sources path. +SOURCESDIR ?= . + # User-friendly check for sphinx-build ifneq ($(MAKECMDGOALS), clean) ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) @@ -23,9 +28,9 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCESDIR) # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCESDIR) .PHONY: help help: diff --git a/doc/manpages/.gitignore b/doc/manpages/.gitignore index 0505537159..2e7d8573f1 100644 --- a/doc/manpages/.gitignore +++ b/doc/manpages/.gitignore @@ -1,3 +1,3 @@ /_templates /_build -!/Makefile +!/Makefile.in diff --git a/doc/manpages/Makefile b/doc/manpages/Makefile.in similarity index 84% rename from doc/manpages/Makefile rename to doc/manpages/Makefile.in index ebbbc31009..f28746cee6 100644 --- a/doc/manpages/Makefile +++ b/doc/manpages/Makefile.in @@ -1,4 +1,11 @@ -include ../frr-sphinx.mk +# This is necessary to support VPATH builds. +srcdir = @srcdir@ +VPATH = @srcdir@ + +# This variable is used as the documentation source location in frr-sphinx.mk +SOURCESDIR = @srcdir@ + +include @srcdir@/../frr-sphinx.mk # ----------------------------------------------------------------------------- # Automake requires that 3rd-party Makefiles recognize these targets. diff --git a/doc/user/.gitignore b/doc/user/.gitignore index 0505537159..2e7d8573f1 100644 --- a/doc/user/.gitignore +++ b/doc/user/.gitignore @@ -1,3 +1,3 @@ /_templates /_build -!/Makefile +!/Makefile.in diff --git a/doc/user/Makefile b/doc/user/Makefile.in similarity index 87% rename from doc/user/Makefile rename to doc/user/Makefile.in index 223f8a64a3..77c6abf917 100644 --- a/doc/user/Makefile +++ b/doc/user/Makefile.in @@ -1,4 +1,11 @@ -include ../frr-sphinx.mk +# This is necessary to support VPATH builds. +srcdir = @srcdir@ +VPATH = @srcdir@ + +# This variable is used as the documentation source location in frr-sphinx.mk +SOURCESDIR = @srcdir@ + +include @srcdir@/../frr-sphinx.mk # ----------------------------------------------------------------------------- # Automake requires that 3rd-party Makefiles recognize these targets. diff --git a/doc/user/conf.py b/doc/user/conf.py index 886403b69d..3fced11024 100644 --- a/doc/user/conf.py +++ b/doc/user/conf.py @@ -342,6 +342,14 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False +# contents of ../extra/frrlexer.py. +# This is read here to support VPATH build. Since this section is execfile()'d +# with the file location, we can safely use a relative path here to save the +# contents of the lexer file for later use even if our relative path changes +# due to VPATH. +with open('../extra/frrlexer.py', 'rb') as lex: + frrlexerpy = lex.read() + # custom extensions here def setup(app): # object type for FRR CLI commands, can be extended to document parent CLI @@ -357,5 +365,5 @@ def setup(app): # # frrlexer = pygments.lexers.load_lexer_from_file('../extra/frrlexer.py', lexername="FRRLexer") custom_namespace = {} - exec(open('../extra/frrlexer.py', 'rb').read(), custom_namespace) + exec(frrlexerpy, custom_namespace) lexers['frr'] = custom_namespace['FRRLexer']() -- 2.39.5