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

2 files changed, 24 insertions, 1 deletions

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index 4f856f3a49..89d22e3c9e 100644
--- 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 4eda5d0506..d91a6d55d6 100644
--- 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).