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.

diff --git a/Makefile.docs b/Makefile.docs
index fe25d583e022e0dd34649c936a348681825854a1..74650845b19305d9d055cb80f38002c4925664d2 100644 (file)
--- 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 5a1311095647c096f5d6e472c30a5e3f152bf9d8..915f19c42aafd00e6f71e2696774c2136ba4ff5d 100644 (file)
--- 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)