Commit 41806ef4 authored by Michael Hanselmann's avatar Michael Hanselmann

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: default avatarMichael Hanselmann <hansmi@google.com>
Reviewed-by: default avatarGuido Trotter <ultrotter@google.com>
parent 6d675203
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
#!/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 "$@"
......@@ -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], [])
......
......@@ -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 = [
......
......@@ -35,6 +35,7 @@ Contents:
ovfconverter.rst
devnotes.rst
news.rst
manpages.rst
glossary.rst
.. toctree::
......
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:
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment