Option to include man pages in documentation

Before this patch, HTML versions of man pages (man/*.rst) were already
built. However, since they are separate from the normal documentation,
their content is not indexed for Sphinx' search functionality.
Additionally it would simply be nice to have everything in one place.

To this end a new configure-time option is added to enable the inclusion
of man pages into the documentation. A dedicated option is necessary to
still be able to provide a static documentation build in the tarball
(not including man pages) as man pages contain build-specific paths and
values. The documentation with man pages is written to the directory
“doc/man-html”.

A future patch will extend Sphinx to link occurences of “:manpage:`…`”
to these man pages.

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Guido Trotter <ultrotter@google.com>

diff --git a/.gitignore b/.gitignore
index f6c5a09..e46c2e1 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -53,10 +53,13 @@
 /doc/api/
 /doc/coverage/
 /doc/html/
+/doc/man-html/
 /doc/install-quick.rst
 /doc/news.rst
 /doc/upgrade.rst
 /doc/hs-lint.html
+/doc/manpages-enabled.rst
+/doc/man-*.rst
 
 # doc/examples
 /doc/examples/bash_completion

diff --git a/Makefile.am b/Makefile.am
index 1ee6f5e..ca4da82 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -135,12 +135,14 @@ BUILDTIME_DIR_AUTOCREATE = \
 
 BUILDTIME_DIRS = \
        $(BUILDTIME_DIR_AUTOCREATE) \
-       doc/html
+       doc/html \
+       doc/man-html
 
 DIRCHECK_EXCLUDE = \
        $(BUILDTIME_DIRS) \
        ganeti-[0-9]*.[0-9]*.[0-9]* \
        doc/html/_* \
+       doc/man-html/_* \
        autom4te.cache
 
 # some helper vars
@@ -171,6 +173,8 @@ CLEANFILES = \
        $(SHELL_ENV_INIT) \
        daemons/daemon-util \
        daemons/ganeti-cleaner \
+       $(mandocrst) \
+       doc/manpages-enabled.rst \
        $(BUILT_EXAMPLES) \
        doc/examples/bash_completion \
        doc/examples/bash_completion-debug \
@@ -403,6 +407,7 @@ docinput = \
        doc/install-quick.rst \
        doc/install.rst \
        doc/locking.rst \
+       doc/manpages-disabled.rst \
        doc/move-instance.rst \
        doc/news.rst \
        doc/ovfconverter.rst \
@@ -412,6 +417,9 @@ docinput = \
        doc/virtual-cluster.rst \
        doc/walkthrough.rst
 
+# Generates file names such as "doc/man-gnt-instance.rst"
+mandocrst = $(addprefix doc/man-,$(notdir $(manrst)))
+
 # Haskell programs to be installed in $PREFIX/bin
 HS_BIN_PROGS=src/htools
 
@@ -580,30 +588,45 @@ HS_BUILT_SRCS_IN = $(patsubst %,%.in,$(HS_BUILT_SRCS))
 
 $(RUN_IN_TEMPDIR): | stamp-directories
 
+doc/html/index.html: ENABLE_MANPAGES =
+doc/man-html/index.html: ENABLE_MANPAGES = 1
+doc/man-html/index.html: doc/manpages-enabled.rst $(mandocrst)
+
 # Note: we use here an order-only prerequisite, as the contents of
 # _autoconf.py are not actually influencing the html build output: it
 # has to exist in order for the sphinx module to be loaded
 # successfully, but we certainly don't want the docs to be rebuilt if
 # it changes
-doc/html/index.html: $(docinput) doc/conf.py configure.ac \
-       $(RUN_IN_TEMPDIR) lib/build/sphinx_ext.py \
+doc/html/index.html doc/man-html/index.html: $(docinput) doc/conf.py \
+       configure.ac $(RUN_IN_TEMPDIR) lib/build/sphinx_ext.py \
        lib/build/shell_example_lexer.py lib/opcodes.py lib/ht.py \
        doc/css/style.css \
        | $(BUILT_PYTHON_SOURCES)
        @test -n "$(SPHINX)" || \
            { echo 'sphinx-build' not found during configure; exit 1; }
-       @mkdir_p@ $(dir $@)
-       PYTHONPATH=. $(RUN_IN_TEMPDIR) $(SPHINX) -q -W -b html \
+if !MANPAGES_IN_DOC
+       if test -n '$(ENABLE_MANPAGES)'; then \
+         echo 'Man pages in documentation were disabled at configure time' >&2; \
+         exit 1; \
+       fi
+endif
+       dir=$(dir $@) && \
+       @mkdir_p@ $$dir && \
+       PYTHONPATH=. ENABLE_MANPAGES=$(ENABLE_MANPAGES) \
+       $(RUN_IN_TEMPDIR) bash autotools/sphinx-wrapper $(SPHINX) -q -W -b html \
            -d . \
            -D version="$(VERSION_MAJOR).$(VERSION_MINOR)" \
            -D release="$(PACKAGE_VERSION)" \
            -D graphviz_dot="$(DOT)" \
-           $(abs_top_builddir)/doc $(CURDIR)/doc/html
-       rm -f doc/html/.buildinfo doc/html/objects.inv
+           -D enable_manpages="$(ENABLE_MANPAGES)" \
+           doc $(CURDIR)/$$dir && \
+       rm -f $$dir/.buildinfo $$dir/objects.inv
        touch $@
 
 doc/html: doc/html/index.html
 
+doc/man-html: doc/man-html/index.html
+
 doc/install-quick.rst: INSTALL
 doc/news.rst: NEWS
 doc/upgrade.rst: UPGRADE
@@ -616,6 +639,34 @@ doc/install-quick.rst doc/news.rst doc/upgrade.rst:
          cat $<; \
        } > $@
 
+doc/manpages-enabled.rst: Makefile | $(built_base_sources)
+       { echo '.. This file is automatically generated, do not edit!'; \
+         echo ''; \
+         echo 'Man pages'; \
+         echo '========='; \
+         echo; \
+         echo '.. toctree::'; \
+         echo '   :maxdepth: 1'; \
+         echo; \
+         for i in $(notdir $(mandocrst)); do \
+           echo "   $$i"; \
+         done | LC_ALL=C sort; \
+       } > $@
+
+doc/man-%.rst: man/%.gen Makefile $(REPLACE_VARS_SED) | $(built_base_sources)
+if MANPAGES_IN_DOC
+       { echo '.. This file is automatically updated at build time from $<.'; \
+         echo '.. Do not edit.'; \
+         echo; \
+         echo "$*"; \
+         echo '=========================================='; \
+         tail -n +3 $< | sed -f $(REPLACE_VARS_SED); \
+       } > $@
+else
+       echo 'Man pages in documentation were disabled at configure time' >&2; \
+       exit 1;
+endif
+
 # Things to build but not to install (add it to EXTRA_DIST if it should be
 # distributed)
 noinst_DATA = \
@@ -625,6 +676,10 @@ noinst_DATA = \
        doc/examples/bash_completion-debug \
        $(manhtml)
 
+if MANPAGES_IN_DOC
+noinst_DATA += doc/man-html
+endif
+
 gnt_scripts = \
        scripts/gnt-backup \
        scripts/gnt-cluster \
@@ -806,6 +861,7 @@ EXTRA_DIST = \
        autotools/convert-constants \
        autotools/docpp \
        autotools/gen-py-coverage \
+       autotools/sphinx-wrapper \
        autotools/testrunner \
        autotools/wrong-hardcoded-paths \
        $(RUN_IN_TEMPDIR) \
@@ -1632,6 +1688,11 @@ dist-hook:
        $(MAKE) $(AM_MAKEFLAGS) regen-vcs-version
        rm -f $(top_distdir)/vcs-version
        cp -p $(srcdir)/vcs-version $(top_distdir)
+if MANPAGES_IN_DOC
+       echo 'Building distribution with man pages included in documentation is' \
+            'not allowed as they can contain fixed paths' >&2; \
+       exit 1
+endif
 
 # a distcheck hook rule for catching revision control directories
 distcheck-hook:

diff --git a/NEWS b/NEWS
index 38e75e2..352a2a8 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -52,6 +52,10 @@ Version 2.7.0 beta1
   allocate the instance, the temporary error code
   :pyeval:`errors.ECODE_TEMP_NORES` is returned. The operation can be
   retried thereafter, with or without opportunistic locking.
+- Man pages can now be included when the documentation is built, in
+  which case the output is in ``doc/man-html``. The configure-time
+  option is ``--enable-manpages-in-doc``. Sphinx 1.0 or higher is
+  required.
 
 
 Version 2.6.2

diff --git a/autotools/run-in-tempdir b/autotools/run-in-tempdir
index 1289783..6622d40 100755 (executable)
--- a/autotools/run-in-tempdir
+++ b/autotools/run-in-tempdir
@@ -9,10 +9,10 @@ tmpdir=$(mktemp -d -t gntbuild.XXXXXXXX)
 trap "rm -rf $tmpdir" EXIT
 
 # fully copy items
-cp -r autotools daemons scripts lib tools qa $tmpdir
+cp -r doc autotools daemons scripts lib tools qa $tmpdir
 
-mkdir $tmpdir/doc
-ln -s $PWD/doc/examples $tmpdir/doc
+#mkdir $tmpdir/doc
+#ln -s $PWD/doc/examples $tmpdir/doc
 
 mkdir $tmpdir/test/
 cp -r test/py $tmpdir/test/py

diff --git a/autotools/sphinx-wrapper b/autotools/sphinx-wrapper
new file mode 100755 (executable)
index 0000000..63b1051
--- /dev/null
+++ b/autotools/sphinx-wrapper
@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+
+# Copyright (C) 2013 Google Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301, USA.
+
+set -e -u -o pipefail
+
+if [[ -e doc/manpages.rst ]]; then
+  echo 'doc/manpages.rst should not exist' >&2
+  exit 1
+fi
+
+if [[ -n "$ENABLE_MANPAGES" ]]; then
+  mv doc/manpages-enabled.rst doc/manpages.rst
+  rm doc/manpages-disabled.rst
+else
+  mv doc/manpages-disabled.rst doc/manpages.rst
+  if [[ -e doc/manpages-enabled.rst ]]; then
+    rm doc/manpages-enabled.rst
+  fi
+fi
+
+exec "$@"

diff --git a/configure.ac b/configure.ac
index 970da47..b09be70 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -375,6 +375,26 @@ then
                             not be possible]))
 fi
 
+AC_ARG_ENABLE([manpages-in-doc],
+  [AS_HELP_STRING([--enable-manpages-in-doc],
+                  m4_normalize([include man pages in HTML documentation
+                                (requires sphinx; default disabled)]))],
+  [case "$enableval" in
+      yes) manpages_in_doc=yes ;;
+      no) manpages_in_doc= ;;
+      *)
+        AC_MSG_ERROR([Bad value $enableval for --enable-manpages-in-doc])
+        ;;
+    esac
+  ],
+  [manpages_in_doc=])
+AM_CONDITIONAL([MANPAGES_IN_DOC], [test -n "$manpages_in_doc"])
+AC_SUBST(MANPAGES_IN_DOC, $manpages_in_doc)
+
+if test -z "$SPHINX" -a -n "$manpages_in_doc"; then
+  AC_MSG_ERROR([Including man pages in HTML documentation requires sphinx])
+fi
+
 # Check for graphviz (dot)
 AC_ARG_VAR(DOT, [dot path])
 AC_PATH_PROG(DOT, [dot], [])

diff --git a/doc/conf.py b/doc/conf.py
index 5540e57..e73b753 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -13,6 +13,8 @@
 
 import sys, os
 
+enable_manpages = bool(os.getenv("ENABLE_MANPAGES"))
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -21,7 +23,7 @@ import sys, os
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = "1.0"
+needs_sphinx = "1.0"
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named "sphinx.ext.*") or your custom ones.
@@ -71,6 +73,13 @@ language = "en"
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
+if enable_manpages:
+  exclude_patterns = []
+else:
+  exclude_patterns = [
+    "man-*.rst",
+    ]
+
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
 exclude_trees = [

diff --git a/doc/index.rst b/doc/index.rst
index 1e054d3..ae2e2af 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -35,6 +35,7 @@ Contents:
    ovfconverter.rst
    devnotes.rst
    news.rst
+   manpages.rst
    glossary.rst
 
 .. toctree::

diff --git a/doc/manpages-disabled.rst b/doc/manpages-disabled.rst
new file mode 100644 (file)
index 0000000..e0a3b9c
--- /dev/null
+++ b/doc/manpages-disabled.rst
@@ -0,0 +1,11 @@
+Man pages
+=========
+
+Inclusion of man pages into documentation was not enabled at build time;
+use ``./configure [...] --enable-manpages-in-doc``.
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End: