From 38d251e11b01f53f74b7e0bfc052e995c93aac1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= Date: Wed, 29 Dec 2021 09:58:48 +0100 Subject: [PATCH 1/2] Set version and release variables in conf.py Some Sphinx variables used in the ARM are only set in Makefile.docs. This works fine when building the ARM using "make", but does not work with Read the Docs, which only looks at conf.py files. Since Read the Docs does not run ./configure, renaming conf.py to conf.py.in and using Autoconf output variables is not a feasible solution. Instead, extend doc/arm/conf.py with some Python code which processes configure.ac using regular expressions and sets the relevant Sphinx variables accordingly. As this solution also works fine when building the ARM using "make", drop the relevant -D options from the list of sphinx-build options used for building the ARM in Makefile.docs. Note that the man_SPHINXOPTS counterparts of the removed -D switches are left intact because doc/man/conf.py is a separate Sphinx project which is only processed using "make" and duplicating the Python code added to doc/arm/conf.py by this commit would be inelegant. --- Makefile.docs | 2 -- doc/arm/conf.py | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/Makefile.docs b/Makefile.docs index 3b2700687b..fe25d583e0 100644 --- a/Makefile.docs +++ b/Makefile.docs @@ -17,9 +17,7 @@ common_SPHINXOPTS = \ ALLSPHINXOPTS = \ $(common_SPHINXOPTS) \ - -D version="$(PACKAGE_VERSION)" \ -D today="$(RELEASE_DATE)" \ - -D release="$(PACKAGE_VERSION)" \ $(SPHINXOPTS) \ $(srcdir) diff --git a/doc/arm/conf.py b/doc/arm/conf.py index 704c96c5d8..f7049afe0f 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -11,6 +11,8 @@ # flake8: noqa: E501 +import re + from typing import List, Tuple from docutils import nodes @@ -105,6 +107,21 @@ project = 'BIND 9' copyright = '2021, Internet Systems Consortium' author = 'Internet Systems Consortium' +m4_vars = {} +with open('../../configure.ac', encoding='utf-8') as configure_ac: + for line in configure_ac: + match = re.match(r'm4_define\(\[(?Pbind_VERSION_[A-Z]+)\], (?P[^)]*)\)dnl', line) + if match: + m4_vars[match.group('key')] = match.group('val') + +version = '%s.%s.%s%s' % ( + m4_vars['bind_VERSION_MAJOR'], + m4_vars['bind_VERSION_MINOR'], + m4_vars['bind_VERSION_PATCH'], + m4_vars['bind_VERSION_EXTRA'], +) +release = version + # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be From e67cdb390a73341802da1deed57254276a294be5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= Date: Wed, 29 Dec 2021 09:58:48 +0100 Subject: [PATCH 2/2] Clarify use of the "today" Sphinx variable Add a comment explaining the purpose of setting the "today" variable in Sphinx invocations to prevent confusion caused by the absence of that variable from reStructuredText sources. Drop the -A command-line option from the sphinx-build invocation for EPUB output as "today" is already set in the ALLSPHINXOPTS variable. --- Makefile.docs | 2 ++ doc/arm/Makefile.am | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/Makefile.docs b/Makefile.docs index fe25d583e0..74650845b1 100644 --- a/Makefile.docs +++ b/Makefile.docs @@ -15,6 +15,8 @@ common_SPHINXOPTS = \ -a \ $(SPHINX_V) +# The "today" variable set below is not directly used in the ARM, but its value +# is implicitly inserted on the title page of the PDF file produced by Sphinx. ALLSPHINXOPTS = \ $(common_SPHINXOPTS) \ -D today="$(RELEASE_DATE)" \ diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 5a13110956..915f19c42a 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -65,7 +65,7 @@ install-singlehtml: singlehtml cp -R $(SPHINXBUILDDIR)/singlehtml/_static/* $(DESTDIR)/$(docdir)/_static/ epub: - $(AM_V_SPHINX)$(SPHINX_BUILD) -b epub -A today=$(RELEASE_DATE) -d $(SPHINXBUILDDIR)/.doctrees/epub $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub + $(AM_V_SPHINX)$(SPHINX_BUILD) -b epub -d $(SPHINXBUILDDIR)/.doctrees/epub $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/epub install-epub: $(INSTALL) -d $(DESTDIR)/$(docdir)