Automate RST HTML generation with doxygen info

In src/doc/Makefile.in, create an "rsthtml" target for generating
release tarball/web site HTML docs in doc/rst_html.  For now,
eliminate support for the bridge to the Doxygen HTML output; just
generate XML output with Doxygen and convert it to RST format.

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

7 files changed, 38 insertions, 120 deletions

diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py
index bcfe6451c3..c423e08e55 100644
--- a/doc/rst_source/conf.py
+++ b/doc/rst_source/conf.py
@@ -27,10 +27,6 @@ import sys, os
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 #extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
 extensions = ['sphinx.ext.autodoc']
-#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
-#doxylink = {
-#    'krb5doxy' : ('path-to-doxygen-tag-file/krb5doxy.tag', 'location-of-doxygen-html-output/'),
-#}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst
index 3ac7cea199..0030400e56 100644
--- a/doc/rst_source/krb_appldev/index.rst
+++ b/doc/rst_source/krb_appldev/index.rst
@@ -10,3 +10,8 @@ Contents
    gssapi.rst
    h5l_mit_apidiff.rst
    princ_handle.rst
+
+.. toctree::
+   :maxdepth: 1
+
+   refs/index.rst
diff --git a/doc/rst_source/mitK5license.rst b/doc/rst_source/mitK5license.rst
index 78fb7cbd99..87fbbcd77f 100644
--- a/doc/rst_source/mitK5license.rst
+++ b/doc/rst_source/mitK5license.rst
@@ -3,5 +3,5 @@
 MIT Kerberos License information
 ================================
 
-.. include::  ../../NOTICE
+.. include::  NOTICE
    :literal:
diff --git a/doc/rst_source/relay/build_this.rst b/doc/rst_source/relay/build_this.rst
index 28ee7e70de..233ec75c88 100644
--- a/doc/rst_source/relay/build_this.rst
+++ b/doc/rst_source/relay/build_this.rst
@@ -1,131 +1,54 @@
 How to build this documentation from the source
 ===============================================
 
-Pre-requisites:
+Pre-requisites for the simple build, or to update man pages:
 
 * Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc”
   extension installed.
 
+Additional prerequisites to include the API reference based on Doxygen
+markup:
 
-How to build the Sphinx based documentation without references to API documentation
------------------------------------------------------------------------------------
+* python 2.5 with the Cheetah, lxml, and xml modules
+* Doxygen
 
-To generate documentation in HTML format, from the
-``trunk/doc/rst_source`` run::
 
-    sphinx-build . output_dir
+Simple build without API reference
+----------------------------------
 
-To produce manpages run::
+To test simple changes to the RST sources, you can build the
+documentation without the Doxygen reference by running, from the doc
+directory::
 
-    sphinx-build -b man . output_dir
+    sphinx-build rst_source test_html
 
-.. note:: The manpages output is controled by **man_pages** tag in the
-          Sphinx configuration file *trunk/doc/rst_source/conf.py*.
+You will see a number of warnings about missing files.  This is
+expected.
 
-How to deploy the Doxygen output in Sphinx project
---------------------------------------------------
 
-The text below is meant to give the instructions on how to incorporate
-MIT Kerberos API reference documentation into Sphinx document
-hierarchy.  The Sphinx API documentation can be constructed without
-(:ref:`Part_A`) or with (:ref:`Part_B`) the bridge to the original
-Doxygen HTML output.
+Updating man pages
+------------------
 
-Pre-requisites:
+Man pages generated from the RST sources, are checked into the src/man
+directory.  To regenerate these files, run ``make rstman`` from the
+doc subdir of a configured build tree.
 
-* python 2.5+ with *Cheetah, lxml* and *xml* extension modules
-  installed;
-* Doxygen documentation generator (http://www.doxygen.org) installed;
-* For "Part B" only:
-  - Sphinx “doxylink” extension;
-  - Doxygen HTML output
+As with the simple build, it is normal to see warnings about missing
+files when rebuilding the man pages.
 
-.. _Part_A:
 
-Part A: Transforming Doxygen XML output into reStructuredText (rst)  without the bridge to Doxygen HTML output
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Building for a release tarball or web site
+------------------------------------------
 
-1. Delete lines containing text "Doxygen reference" from the template
-   files func_document.tmpl and type_document.tmpl located in
-   trunk/doc/rst_tools directory;
+To generate documentation in HTML format, run ``make rsthtml`` in the
+``doc`` subdir 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.
 
-2. In the Doxygen configuration file (``trunk/src/Doxyfile``) set
-   **GENERATE_XML** flag to ``YES``.  Generate Doxygen XML output.  To
-   do so from the command line from the source directory
-   (``trunk/src``) run::
+You can also do this from an unconfigured source tree with::
 
-        doxygen
-
-   The **XML_OUTPUT** tag specifies the location of the Doxygen XML
-   output.  The default location for this setup is ``trunk/out/xml``.
-
-3. Suppose the Doxygen XML output is located in ``trunk/out/xml``
-   directory and the desired name for the reStructuredText output
-   directory is ``rst_dir``.  From ``trunk/doc/rst_tools`` run::
-
-       python doxy.py –i  ../../out/xml –o rst_dir –t func
-
-   This will result in the storing the API function documentation
-   files in rst format in ``rst_dir``.
-
-   .. note:: The file names are constructed based on the function
-             name.  For example, the file for krb5_build_principal()
-             will be krb5_build_principal.rst
-
-   Run::
-
-       python doxy.py –i ../../out/xml –o rst_dir –t typedef
-
-   It is similar to the API function conversion, but for data types.
-   The result will be stored under ``rst_dir/types`` directory
-
-   Alternatively, running::
-
-       python doxy.py –i  ../../out/xml  –o rst_dir
-
-   or
-
-       python doxy.py –i  ../../out/xml  –o rst_dir -t all
-
-   converts Doxygen XML output into reStructuredText format files both
-   for API functions and data types;
-
-4. In ``trunk/doc/krb_appldev/index.rst`` add the following section to
-   point to the API references::
-
-       .. toctree::
-          :maxdepth: 1
-
-          refs/index.rst
-
-5. Copy the content of
-
-   * ``rst_dir`` into ``krb_appldev/refs/api`` directory, and
-   * ``rst_dir/types`` into ``krb_appldev/refs/types`` directory;
-
-6. Rebuild Sphinx source. From the ``trunk/doc/rst_source`` run::
-
-       sphinx-build .  output_dir
-
-
-.. _Part_B:
-
-Part B: Bridge to Doxygen HTML output
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Transform Doxygen XML output into reStructuredText.
-   In src/Doxygen configuration file request generation of the tag
-   file and XML output::
-
-       GENERATE_TAGFILE       = krb5doxy.tag
-       GENERATE_XML           = YES
-
-2. Modify Sphinx conf.py file to point to the “doxylink” extension and
-   Doxygen tag file::
-
-       extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
-       doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') }
-
-   where *doxy_html_dir* is the location of the Doxygen HTML output
-
-3. Continue with steps 3 - 6 of Part A.
+    cd src/doc
+    make -f Makefile.in top_srcdir=.. PYTHON=python rsthml
+    make -f Makefile.in clean
diff --git a/doc/rst_tools/define_document.tmpl b/doc/rst_tools/define_document.tmpl
index b578ba9fc4..6e9249597d 100644
--- a/doc/rst_tools/define_document.tmpl
+++ b/doc/rst_tools/define_document.tmpl
@@ -14,8 +14,6 @@ $title
 
 
 
-:krb5doxy:`Doxygen reference to $composite.name  <$composite.name>`
-
 ..
 .. data:: $composite.name
 ..
diff --git a/doc/rst_tools/func_document.tmpl b/doc/rst_tools/func_document.tmpl
index eadf4dfc83..6a8874de7e 100644
--- a/doc/rst_tools/func_document.tmpl
+++ b/doc/rst_tools/func_document.tmpl
@@ -6,8 +6,6 @@
 $title
 #echo ''.join(['=']*len($title)) #
 
-:krb5doxy:`Doxygen reference to $function.name  <$function.name>`
-
 ..
 
 .. c:function:: $signature
diff --git a/doc/rst_tools/type_document.tmpl b/doc/rst_tools/type_document.tmpl
index 57d1131c77..1be6465d2c 100644
--- a/doc/rst_tools/type_document.tmpl
+++ b/doc/rst_tools/type_document.tmpl
@@ -14,8 +14,6 @@ $title
 
 
 
-:krb5doxy:`Doxygen reference to $composite.name  <$composite.name>`
-
 ..
 .. c:type:: $composite.name
 ..