svn rev #25795: trunk/ doc/rst_source/ doc/rst_source/relay/ src/doc/

[ghudson@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=25795
Commit By: ghudson
Log Message:
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.


Changed Files:
U   trunk/doc/rst_source/conf.py
U   trunk/doc/rst_source/relay/build_this.rst
U   trunk/src/doc/Makefile.in
Modified: trunk/doc/rst_source/conf.py
===================================================================
--- trunk/doc/rst_source/conf.py	2012-03-28 21:11:01 UTC (rev 25794)
+++ trunk/doc/rst_source/conf.py	2012-03-28 21:11:06 UTC (rev 25795)
@@ -214,6 +214,9 @@
     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>`'

Modified: trunk/doc/rst_source/relay/build_this.rst
===================================================================
--- trunk/doc/rst_source/relay/build_this.rst	2012-03-28 21:11:01 UTC (rev 25794)
+++ trunk/doc/rst_source/relay/build_this.rst	2012-03-28 21:11:06 UTC (rev 25795)
@@ -46,14 +46,34 @@
 ------------------------------------------
 
 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).

Modified: trunk/src/doc/Makefile.in
===================================================================
--- trunk/src/doc/Makefile.in	2012-03-28 21:11:01 UTC (rev 25794)
+++ trunk/src/doc/Makefile.in	2012-03-28 21:11:06 UTC (rev 25795)
@@ -5,6 +5,8 @@
 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 @@
 	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 @@
 	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