Add doc target with configured path substitutions

Add a new target "substhtml" in src/doc to create HTML documentation
with configured paths, suitable for installation by an OS package.
The build target generates a file named paths.py containing the
directory substitutions, copies it into the rst_composite directory,
and instructs conf.py to use it with the "pathsubs" tag.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25795 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 4f856f3a496b8ffe5f9c6f29f353a8f325fda82c..89d22e3c9e591607035bff290d1b42cc0af2f643 100644 (file)
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -214,6 +214,9 @@ if 'mansubs' in tags:
     libdir = '``@LIBDIR@``'
     localstatedir = '``@LOCALSTATEDIR@``'
     sysconfdir = '``@SYSCONFDIR@``'
+elif 'pathsubs' in tags:
+    # Read configured paths from a file produced by the build system.
+    execfile('paths.py')
 else:
     bindir = ':ref:`BINDIR <paths>`'
     sbindir = ':ref:`SBINDIR <paths>`'

diff --git a/doc/rst_source/relay/build_this.rst b/doc/rst_source/relay/build_this.rst
index 4eda5d0506cd85a6d413bae6aacd2275f857481e..d91a6d55d6100db8b4a4dab6f66f4f34238e2001 100644 (file)
--- a/doc/rst_source/relay/build_this.rst
+++ b/doc/rst_source/relay/build_this.rst
@@ -46,14 +46,34 @@ Building for a release tarball or web site
 ------------------------------------------
 
 To generate documentation in HTML format, run ``make rsthtml`` in the
-``doc`` subdir of a configured build tree (the build directory
+``doc`` subdirectory of a configured build tree (the build directory
 corresponding to ``src/doc``, not the top-level ``doc`` directory).
 The output be placed in the top-level ``doc/rst_html`` directory.
 This build will include the API reference generated from Doxygen
 markup in the source tree.
 
+Documentation generated this way will use symbolic names for paths
+(like ``BINDIR`` for the directory containing user programs), with the
+symbolic names being links to a table showing typical values for those
+paths.
+
 You can also do this from an unconfigured source tree with::
 
     cd src/doc
     make -f Makefile.in top_srcdir=.. PYTHON=python rsthml
     make -f Makefile.in clean
+
+
+Building for an OS package or site documentation
+------------------------------------------------
+
+To generate documentation specific to a build of MIT krb5 as you have
+configured it, run ``make substhtml`` in the ``doc`` subdirectory of a
+configured build tree (the build directory corresponding to
+``src/doc``, not the top-level ``doc`` directory).  The output will be
+placed in the ``rst_html_subst`` subdirectory of that build directory.
+This build will include the API reference.
+
+Documentation generated this way will use concrete paths (like
+``/usr/local/bin`` for the directory containing user programs, for a
+default custom build).

diff --git a/src/doc/Makefile.in b/src/doc/Makefile.in
index ed3122082fbe515af7c8200f5fd537c1d1515f97..95ece80e265d5149d369a23e4e0997b05da4079e 100644 (file)
--- a/src/doc/Makefile.in
+++ b/src/doc/Makefile.in
@@ -5,6 +5,8 @@ SPHINX_BUILD=sphinx-build
 DOXYGEN=doxygen
 
 docsrc=$(top_srcdir)/../doc
+localstatedir=@localstatedir@
+sysconfdir=@sysconfdir@
 
 # Create HTML documentation in $(docsrc)/rst_html suitable for a
 # release tarball or the web site (that is, without substitutions for
@@ -16,10 +18,18 @@ rsthtml: composite
        rm -rf $(docsrc)/rst_html
        $(SPHINX_BUILD) -q rst_composite $(docsrc)/rst_html
 
+# Create HTML documentation in rst_html_subst suitable for
+# installation by an OS package, with substitutions for configured
+# paths.
+substhtml: composite paths.py
+       rm -rf rst_html_subst
+       cp paths.py rst_composite
+       $(SPHINX_BUILD) -t pathsubs -q rst_composite rst_html_subst
+
 # Use doxygen to generate API documentation, translate it into RST
 # format, and then create a composite of $(docsrc)/rst_source, the
 # generated files, and the NOTICE file in rst_composite.  Used by the
-# rsthtml and ___ targets.
+# rsthtml and substhtml targets.
 composite: Doxyfile
        rm -rf doxy rst_apiref rst_composite
        $(DOXYGEN)
@@ -35,5 +45,13 @@ Doxyfile: $(srcdir)/Doxyfile.in
        sed -e 's|@SRC@|$(top_srcdir)|g' \
            -e 's|@DOC@|$(top_srcdir)/../doc|g' $(srcdir)/Doxyfile.in > $@
 
+paths.py:
+       rm -f $@
+       echo 'bindir = "``$(CLIENT_BINDIR)``"' > $@
+       echo 'sbindir = "``$(SERVER_BINDIR)``"' >> $@
+       echo 'libdir = "``$(KRB5_LIBDIR)``"' >> $@
+       echo 'localstatedir = "``$(localstatedir)``"' >> $@
+       echo 'sysconfdir = "``$(sysconfdir)``"' >> $@
+
 clean::
-       rm -rf doxy rst_apiref rst_composite Doxyfile
+       rm -rf doxy rst_apiref rst_composite rst_html_subst Doxyfile paths.py