fixed building docs on some systems

2025-09-02 23:15:20 +00:00 · 2019-07-24 09:58:40 +02:00
parent e29ded9359
commit c196f4c2b2
5 changed files with 90 additions and 22 deletions
--- a/configure.ac
+++ b/configure.ac
@@ -1442,27 +1442,49 @@ AC_ARG_WITH([sphinx],
  AC_HELP_STRING([--with-sphinx=PATH], [path to sphinx-build tool]),
  [sphinx_path="$withval"])

-if test "x$enable_generate_docs" != xno ; then
+AC_ARG_WITH([pdflatex],
+  AC_HELP_STRING([--with-pdflatex=PATH], [path to pdflatex tool]),
+  [pdflatex_path="$withval"])

+if test "x$enable_generate_docs" != xno ; then
  # Check for sphinx-build
  if test -z "$sphinx_path"; then
     AC_PATH_PROGS([SPHINXBUILD], [sphinx-build sphinx-build-3])
  else
     SPHINXBUILD="$sphinx_path"
  fi
-  echo $SPHINXBUILD
+
  if test -z "$SPHINXBUILD"; then
    AC_MSG_ERROR([sphinx-build not found; it is required for --enable-generate-docs, please see http://www.sphinx-doc.org/en/master/usage/installation.html for details])
  else
    AC_MSG_CHECKING([whether $SPHINXBUILD works])
-    # run sphinx to see if it works
-    # We should probably do a more thorough checks
    $SPHINXBUILD --version
    if test $? -ne 0 ; then
      AC_MSG_ERROR("Error with $SPHINXBUILD --version")
    fi
    AC_MSG_RESULT(yes (found in $SPHINXBUILD))
  fi
+
+  # Check for pdflatex
+  if test -z "$pdflatex_path"; then
+     AC_PATH_PROG([PDFLATEX], [pdflatex])
+  else
+     PDFLATEX="$pdflatex_path"
+  fi
+
+  if test -z "$PDFLATEX"; then
+    AC_MSG_ERROR([pdflatex not found; it is expected for --enable-generate-docs if not explicitly disabled by ???])
+  elif test "x$PDFLATEX" == "xno"; then
+    :
+  else
+    AC_MSG_CHECKING([whether $PDFLATEX works])
+    $PDFLATEX --version
+    if test $? -ne 0 ; then
+      AC_MSG_ERROR("Error with $PDFLATEX --version")
+    fi
+    AC_MSG_RESULT(yes (found in $PDFLATEX))
+  fi
+  AM_CONDITIONAL(HAVE_PDFLATEX, test "x$PDFLATEX" != "xno")
 fi

 AM_CONDITIONAL(GENERATE_DOCS, test x$enable_generate_docs != xno)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = sphinx devel
+SUBDIRS = sphinx

 EXTRA_DIST = images/kea-logo-100x70.png

--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -231,7 +231,10 @@ api_files+=$(srcdir)/api/version-get.json
 EXTRA_DIST += $(api_files)


-all: html mans pdf
+all: html mans
+if HAVE_PDFLATEX
+all: pdf
+endif

 $(srcdir)/kea-messages.rst: $(mes_files) mes2doc.py
 	$(srcdir)/mes2doc.py -o $@ $(mes_files)
@@ -241,8 +244,22 @@ $(srcdir)/api.rst: $(api_files) api2doc.py
 	$(srcdir)/api2doc.py -o $@ $(api_files)


+PDFLATEX_AND_OPTS=$(PDFLATEX) -interaction nonstopmode
+
 pdf: $(main_sources)
-	$(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
+	$(SPHINXBUILD) -M latex $(srcdir) $(sphinxbuilddir) $(sphinxopts)
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-arm.tex
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-arm.tex
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-arm.tex
+	-cd $(sphinxbuilddir)/latex && makeindex -s python.ist kea-arm.idx
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-arm.tex
+	cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-arm.tex
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-messages.tex
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-messages.tex
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-messages.tex
+	-cd $(sphinxbuilddir)/latex && makeindex -s python.ist kea-messages.idx
+	-cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-messages.tex
+	cd $(sphinxbuilddir)/latex && $(PDFLATEX_AND_OPTS) kea-messages.tex

 html: $(main_sources)
 	$(SPHINXBUILD) -M html $(srcdir) $(sphinxbuilddir) $(sphinxopts)
--- a/doc/sphinx/arm/install.rst
+++ b/doc/sphinx/arm/install.rst
@@ -114,7 +114,9 @@ the system:

 -  The documentation generation tools `Sphinx <https://www.sphinx-doc.org/>`_,
   texlive with its extensions and Doxygen, if using the --enable-generate-docs
-   configuration option to create the documentation.
+   configuration option to create the documentation. Particularly,
+   in case of Fedora: python3-sphinx, texlive and texlive-collection-latexextra;
+   in case of Ubuntu: python3-sphinx, python3-sphinx-rtd-theme and texlive???

 Visit ISC's Knowledgebase at https://kb.isc.org/docs/installing-kea for
 system-specific installation tips.
--- a/hammer.py
+++ b/hammer.py
@@ -40,12 +40,21 @@ import xml.etree.ElementTree as ET


 SYSTEMS = {
-    'fedora': ['27', '28', '29', '30'],
+    'fedora': ['27',  # EOLed
+               '28',  # EOLed
+               '29',
+               '30'],
    'centos': ['7'],
    'rhel': ['8'],
-    'ubuntu': ['16.04', '18.04', '18.10', '19.04'],
-    'debian': ['8', '9', '10'],
-    'freebsd': ['11.2', '12.0'],
+    'ubuntu': ['16.04',
+               '18.04',
+               '18.10',  # EOLed
+               '19.04'],
+    'debian': ['8',
+               '9',
+               '10'],
+    'freebsd': ['11.2',
+                '12.0'],
 }

 # pylint: disable=C0326
@@ -1021,9 +1030,7 @@ def prepare_system_local(features, check_times):
            packages.extend(['rpm-build', 'python2-devel', 'python3-devel'])

        if 'docs' in features:
-            packages.extend(['python3-sphinx', 'texlive', 'texlive-fncychap', 'texlive-tabulary',
-                             'texlive-framed', 'texlive-wrapfig', 'texlive-upquote',
-                             'texlive-capt-of', 'texlive-needspace', 'latexmk'])
+            packages.extend(['python3-sphinx', 'texlive', 'texlive-collection-latexextra'])

        if 'mysql' in features:
            execute('sudo dnf remove -y community-mysql-devel || true')
@@ -1061,7 +1068,7 @@ def prepare_system_local(features, check_times):
            packages.extend(['rpm-build', 'python2-devel'])

        if 'docs' in features:
-            packages.extend(['libxslt', 'elinks', 'docbook-style-xsl'])
+            packages.extend(['python36-virtualenv'])

        if 'mysql' in features:
            packages.extend(['mariadb', 'mariadb-server', 'mariadb-devel'])
@@ -1077,6 +1084,12 @@ def prepare_system_local(features, check_times):

        install_pkgs(packages, env=env, check_times=check_times)

+        if 'docs' in features:
+            execute('virtualenv-3 ~/venv',
+                    env=env, timeout=60, check_times=check_times)
+            execute('~/venv/bin/pip install sphinx sphinx-rtd-theme',
+                    env=env, timeout=120, check_times=check_times)
+
        if 'unittest' in features:
            _install_gtest_sources()

@@ -1145,7 +1158,7 @@ def prepare_system_local(features, check_times):
                packages.append('googletest')

        if 'docs' in features:
-            packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'latexmk'])
+            packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme'])

        if 'native-pkg' in features:
            packages.extend(['build-essential', 'fakeroot', 'devscripts'])
@@ -1189,9 +1202,12 @@ def prepare_system_local(features, check_times):
                packages.append('googletest')

        if 'docs' in features:
-            packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme', 'latexmk'])
+            if revision == '8':
+                packages.extend(['virtualenv'])
+            else:
+                packages.extend(['python3-sphinx', 'python3-sphinx-rtd-theme'])
                if revision == '9':
-                packages.append('texlive-generic-extra')
+                    packages.extend(['texlive-generic-extra'])

        if 'native-pkg' in features:
            packages.extend(['build-essential', 'fakeroot', 'devscripts'])
@@ -1218,6 +1234,12 @@ def prepare_system_local(features, check_times):

        install_pkgs(packages, env=env, timeout=240, check_times=check_times)

+        if 'docs' in features and revision == '8':
+            execute('virtualenv -p /usr/bin/python3 ~/venv',
+                    env=env, timeout=60, check_times=check_times)
+            execute('~/venv/bin/pip install sphinx typing sphinx-rtd-theme',
+                    env=env, timeout=120, check_times=check_times)
+
        if 'cql' in features and revision != '8':
            # there is no libuv1 package in case of debian 8
            _install_cassandra_deb(system, revision, env, check_times)
@@ -1334,6 +1356,11 @@ def _build_binaries_and_run_ut(system, revision, features, tarball_path, env, ch
            raise NotImplementedError
    if 'docs' in features and not (system == 'rhel' and revision == '8'):
        cmd += ' --enable-generate-docs'
+        if system == 'debian' and revision == '8':
+            cmd += ' --with-sphinx=$HOME/venv/bin/sphinx-build'
+        elif system == 'centos' and revision == '7':
+            cmd += ' --with-sphinx=$HOME/venv/bin/sphinx-build'
+            cmd += ' --with-pdflatex=no'
    if 'radius' in features:
        cmd += ' --with-freeradius=/usr/local'
    if 'shell' in features:
@@ -1362,7 +1389,7 @@ def _build_binaries_and_run_ut(system, revision, features, tarball_path, env, ch
    if 'distcheck' in features:
        cmd = 'make distcheck'
    else:
-        cmd = 'make -j%s' % cpus
+        cmd = 'make -C doc/sphinx -j%s' % cpus
    execute(cmd, cwd=src_path, env=env, timeout=timeout, check_times=check_times, dry_run=dry_run)

    if 'unittest' in features: