From: Greg Hudson <ghudson@mit.edu>
Date: Wed, 28 Mar 2012 21:11:06 +0000 (+0000)
Subject: Add doc target with configured path substitutions
X-Git-Url: http://git.tremily.us/?p=krb5.git;a=commitdiff_plain;h=ad10a94d11676da906feb0d8b9394c5b2ed394aa

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 4f856f3a4..89d22e3c9 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 4eda5d050..d91a6d55d 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).
diff --git a/src/doc/Makefile.in b/src/doc/Makefile.in
index ed3122082..95ece80e2 100644
--- 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