Merge pull request #5198 from elliefm/v313/cyr-1477-sphinx-rtd-depend…

…ency

configure.ac: want sphinx_rtd_theme for doc builds

changes/next/docs-sphinx-rtd-theme

@@ -0,0 +1,21 @@
+Description:
+
+Documentation now uses the theme from Read the Docs rather than the old
+custom one.
+
+
+Config changes:
+
+None
+
+
+Upgrade instructions:
+
+If you wish to (re)build the documentation, you will need to have the python
+module "sphinx_rtd_theme" available.  On Debian, this is in the
+python3-sphinx-rtd-theme package.
+
+
+GitHub issue:
+
+None

configure.ac

@@ -2328,7 +2328,7 @@ AS_IF(
     )]
 )
 
-dnl documentation generation (sphinx, perl2rst, gitpython)
+dnl documentation generation (sphinx, sphinx_rtd_theme, perl2rst, gitpython)
 AC_DEFUN([WARN_DOCDEPS], [
     AM_COND_IF([ENABLE_RELEASE_CHECKS],
                [AC_MSG_ERROR([No $1, cannot regenerate docs])],
@@ -2364,8 +2364,28 @@ AS_CASE([$HAVE_PYMOD_GIT],
             [*],    [WARN_DOCDEPS([GitPython])])
 ])
 
+# XXX icky and slightly bogus* to have to duplicate this python2/python3 mess,
+# XXX but i think it's not worth generalising now when we'll surely drop
+# XXX python2 support sooner or later anyway
+# XXX (* this check inherits the successful PYTHON from the check above, and
+# XXX doesn't actually check both despite looking like it will.  that's fine...
+# XXX it only works if both modules are installed for the same python anyway!)
+AX_PYTHON_MODULE([sphinx_rtd_theme], [], [python2])
+AS_CASE([$HAVE_PYMOD_SPHINX_RTD_THEME],
+        [yes],  [],
+        [*],    [
+    unset PYTHON # work around AX_PYTHON_MODULE not cleaning up
+    AX_PYTHON_MODULE([sphinx_rtd_theme], [], [python3])
+    AS_CASE([$HAVE_PYMOD_SPHINX_RTD_THEME],
+            [yes],  [],
+            [*],    [WARN_DOCDEPS([sphinx_rtd_theme])])
+])
+
 AM_CONDITIONAL([HAVE_SPHINX_BUILD],
-    [ test -n "$SPHINX_BUILD" -a x"$have_ppvr" = xyes -a x"$HAVE_PYMOD_GIT" = xyes])
+    [ test -n "$SPHINX_BUILD" \
+           -a x"$have_ppvr" = xyes \
+           -a x"$HAVE_PYMOD_GIT" = xyes \
+           -a x"$HAVE_PYMOD_SPHINX_RTD_THEME" = xyes])
 
 AH_TOP([
 /*
@@ -2644,6 +2664,7 @@ iCalendar features:
 
 Documentation dependencies:
    sphinx-build:       $SPHINX_BUILD
+   sphinx_rtd_theme:   $HAVE_PYMOD_SPHINX_RTD_THEME
    Pod::POM::View::Restructured:  $have_ppvr
    GitPython:          $HAVE_PYMOD_GIT
 

docsrc/imap/developer/compiling.rst

@@ -97,8 +97,9 @@ and included in the release, and do not normally need to be re-built.
     `perl(Pod::POM::View::Restructured)`_,,, "no", "Needed to generate man
     pages. This has to be available to the system-wide perl interpreter, found
     by ``which``."
-    `python(GitPython)`_,,, "no", "Needed for building the documentation."
-    `python(Sphinx)`_,,, "no", "Needed for building the documentation."
+    `python(GitPython)`_,python3-git,, "no", "Needed for building the documentation."
+    `python(sphinx_rtd_theme)`_,python3-sphinx-rtd-theme,, "no", "Needed for building the documentation."
+    `python(Sphinx)`_,python3-sphinx,, "no", "Needed for building the documentation."
     `transfig`_, transfig, transfig, "no", "Also known as fig2dev, transfig is
     an artifact from the old days, and is only used for generation of a couple
     of png files in the legacy documentation (doc/legacy/murder.png and
@@ -224,6 +225,7 @@ Other
 .. _perl-devel: http://www.perl.org/
 .. _postgresql: http://www.postgresql.org/
 .. _python(GitPython): https://github.com/gitpython-developers/GitPython
+.. _python(sphinx_rtd_theme): https://github.com/readthedocs/sphinx_rtd_theme
 .. _python(Sphinx): https://www.sphinx-doc.org/
 .. _shapelib: http://shapelib.maptools.org
 .. _libsrs2: https://www.libsrs2.org/