From ad10a94d11676da906feb0d8b9394c5b2ed394aa Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Wed, 28 Mar 2012 21:11:06 +0000 Subject: [PATCH] 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 --- doc/rst_source/conf.py | 3 +++ doc/rst_source/relay/build_this.rst | 22 +++++++++++++++++++++- src/doc/Makefile.in | 22 ++++++++++++++++++++-- 3 files changed, 44 insertions(+), 3 deletions(-) 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 `' sbindir = ':ref:`SBINDIR `' 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 -- 2.26.2