(#7301) Build man pages for RPM and deb packages using Sphinx

build/cmake/CondorConfigure.cmake

@@ -1424,8 +1424,7 @@ message(STATUS "----- End compiler options/flags check -----")
 message(STATUS "----- Begin CMake Var DUMP -----")
 message(STATUS "CMAKE_STRIP: ${CMAKE_STRIP}")
 message(STATUS "LN: ${LN}")
-message(STATUS "LATEX: ${LATEX}")
-message(STATUS "LATEX2HTML: ${LATEX2HTML}")
+message(STATUS "SPHINXBUILD: ${SPHINXBUILD}")
 
 # if you are building in-source, this is the same as CMAKE_SOURCE_DIR, otherwise
 # this is the top level directory of your build tree

build/packaging/new-debian/control

@@ -13,9 +13,7 @@ Build-Depends: autotools-dev,
                dh-autoreconf,
                dh-python,
                flex,
-               gsoap (>= 2.7.17-1~),
                help2man,
-               latex2html,
                libboost-filesystem-dev,
                libboost-program-options-dev,
                libboost-python-dev,
@@ -43,8 +41,8 @@ Build-Depends: autotools-dev,
                libxss-dev,
                po-debconf,
                python-dev,
-               texlive-font-utils,
-               transfig,
+               python-sphinx,
+               python-sphinx-rtd-theme,
                uuid-dev,
                zlib1g-dev
 Build-Conflicts: liblog4cpp5-dev

build/packaging/new-debian/patches/old-sphinx.patch

@@ -0,0 +1,24 @@
+These patches allow the man pages to be built using older version
+of Sphinx. These patches may be dropped for more recent versions.
+Currently, our man pages are built on submit-3.batlab.org and
+python-sphinx10 is installed from EPEL 6. (version 1.0.8)
+These components are not used for the man pages.
+
+* sphnix.ext.napoleon appears in version 1.3
+* sphinx.ext.autosectionlabel appears in version 1.4
+
+diff --git a/docs/conf.py b/docs/conf.py
+index eb88a06..2da06e6 100644
+--- a/docs/conf.py
++++ b/docs/conf.py
+@@ -32,10 +32,8 @@ sys.path.append(os.path.abspath('extensions'))
+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+ # ones.
+ extensions = [
+-    'sphinx.ext.autosectionlabel',
+     'sphinx.ext.intersphinx',
+     'sphinx.ext.autodoc',
+-    'sphinx.ext.napoleon',
+     'ticket',
+     'macro',
+     'index',

build/packaging/new-debian/patches/series

@@ -1 +1,2 @@
 # in order of upstream compatibility and invasiveness
+old-sphinx.patch

build/packaging/new-debian/rules

@@ -70,12 +70,12 @@ override_dh_shlibdeps:
 
 doc/build:
 	mkdir -p $@
-	# Need a more recent version htlatex for this
+	# TODO: Build the manual now that we are using Sphinx
 	# $(MAKE) -C doc ref.html
 	# mv doc/ref.html $@/html
-	$(MAKE) -C doc just-man-pages
+	$(MAKE) -C docs man
 	mkdir -p $@/man
-	mv doc/man/man1/* $@/man
+	mv docs/_build/man/* $@/man
 
 
 override_dh_auto_install:
@@ -115,7 +115,7 @@ override_dh_auto_clean:
 		src/condor_tests/batch_test.pl
 	-rm src/condor_utils/param_info.c
 	# docs
-	$(MAKE) -C doc clean
+	$(MAKE) -C docs clean
 	-rm -f doc/condor-*-Manual.tar
 	-rm -rf doc/just-man-pages
 	-rm -rf doc/build

build/packaging/srpm/condor.spec

@@ -214,6 +214,7 @@ Source122: glibc-2.5-20061008T1257-x86_64-p0.tar.gz
 Source123: zlib-1.2.3.tar.gz
 %endif
 
+Patch1: old-sphinx.patch
 
 #% if 0%osg
 Patch8: osg_sysconfig_in_init_script.patch
@@ -354,10 +355,15 @@ BuildRequires: systemd-units
 Requires: systemd
 %endif
 
-BuildRequires: transfig
-BuildRequires: latex2html
-# We don't build the manual (yet)
-#BuildRequires: texlive-epstopdf
+%if 0%{?rhel} == 6
+BuildRequires: python-sphinx10 python-sphinx_rtd_theme
+%else
+%ifarch %{ix86}
+BuildRequires: python-sphinx
+%else
+BuildRequires: python-sphinx python-sphinx_rtd_theme
+%endif
+%endif
 
 Requires: /usr/sbin/sendmail
 Requires: condor-classads = %{version}-%{release}
@@ -823,6 +829,8 @@ exit 0
 %setup -q -n %{name}-%{tarball_version}
 %endif
 
+%patch1 -p1
+
 %if 0%{?osg} || 0%{?hcc}
 %patch8 -p1
 %endif
@@ -838,7 +846,11 @@ find src -perm /a+x -type f -name "*.[Cch]" -exec chmod a-x {} \;
 %build
 
 # build man files
-make -C doc just-man-pages
+%if 0%{?rhel} == 6
+make -C docs SPHINXBUILD=sphinx-1.0-build man
+%else
+make -C docs man
+%endif
 
 export CMAKE_PREFIX_PATH=/usr
 
@@ -1007,7 +1019,7 @@ populate %_libexecdir/condor %{buildroot}/usr/libexec/*
 
 # man pages go under %{_mandir}
 mkdir -p %{buildroot}/%{_mandir}
-mv %{buildroot}/usr/man/man1 %{buildroot}/%{_mandir}
+mv %{buildroot}/usr/man %{buildroot}/%{_mandir}/man1
 
 mkdir -p %{buildroot}/%{_sysconfdir}/condor
 # the default condor_config file is not architecture aware and thus

build/packaging/srpm/old-sphinx.patch

@@ -0,0 +1,47 @@
+These patches allow the man pages to be built using older version
+of Sphinx. These patches may be dropped for more recent versions.
+Currently, our man pages are built on submit-3.batlab.org and
+python-sphinx10 is installed from EPEL 6. (version 1.0.8)
+These components are not used for the man pages.
+
+* process_index_entry appears in version 1.1
+* sphnix.ext.napoleon appears in version 1.3
+* sphinx.ext.autosectionlabel appears in version 1.4
+
+diff --git a/docs/conf.py b/docs/conf.py
+index eb88a06..2da06e6 100644
+--- a/docs/conf.py
++++ b/docs/conf.py
+@@ -32,10 +32,8 @@ sys.path.append(os.path.abspath('extensions'))
+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+ # ones.
+ extensions = [
+-    'sphinx.ext.autosectionlabel',
+     'sphinx.ext.intersphinx',
+     'sphinx.ext.autodoc',
+-    'sphinx.ext.napoleon',
+     'ticket',
+     'macro',
+     'index',
+diff --git a/docs/extensions/index.py b/docs/extensions/index.py
+index 7565e0b..c02bf21 100644
+--- a/docs/extensions/index.py
++++ b/docs/extensions/index.py
+@@ -5,7 +5,7 @@ from docutils import nodes, utils
+ from docutils.parsers.rst import Directive
+ from sphinx import addnodes
+ from sphinx.errors import SphinxError
+-from sphinx.util.nodes import split_explicit_title, process_index_entry, \
++from sphinx.util.nodes import split_explicit_title, \
+     set_role_source_info
+
+ def dump(obj):
+@@ -23,7 +23,7 @@ def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+     title = utils.unescape(title)
+     target = utils.unescape(target)
+     # if an explicit target is given, we can process it as a full entry
+-    if has_explicit_title:
++    if False:
+         entries = process_index_entry(target, targetid)
+     # otherwise we just create a "single" entry
+     else: