svn rev #25791: trunk/ doc/rst_source/ doc/rst_source/krb_appldev/ doc/rst_source/relay/ ...
ghudson@MIT.EDU
ghudson at MIT.EDU
Tue Mar 27 22:03:33 EDT 2012
http://src.mit.edu/fisheye/changelog/krb5/?cs=25791
Commit By: ghudson
Log Message:
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.
Changed Files:
U trunk/doc/rst_source/conf.py
U trunk/doc/rst_source/krb_appldev/index.rst
U trunk/doc/rst_source/mitK5license.rst
U trunk/doc/rst_source/relay/build_this.rst
U trunk/doc/rst_tools/define_document.tmpl
U trunk/doc/rst_tools/func_document.tmpl
U trunk/doc/rst_tools/type_document.tmpl
D trunk/src/Doxyfile
U trunk/src/Makefile.in
A trunk/src/doc/Doxyfile.in
U trunk/src/doc/Makefile.in
Modified: trunk/doc/rst_source/conf.py
===================================================================
--- trunk/doc/rst_source/conf.py 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_source/conf.py 2012-03-28 02:03:33 UTC (rev 25791)
@@ -27,10 +27,6 @@
# 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']
Modified: trunk/doc/rst_source/krb_appldev/index.rst
===================================================================
--- trunk/doc/rst_source/krb_appldev/index.rst 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_source/krb_appldev/index.rst 2012-03-28 02:03:33 UTC (rev 25791)
@@ -10,3 +10,8 @@
gssapi.rst
h5l_mit_apidiff.rst
princ_handle.rst
+
+.. toctree::
+ :maxdepth: 1
+
+ refs/index.rst
Modified: trunk/doc/rst_source/mitK5license.rst
===================================================================
--- trunk/doc/rst_source/mitK5license.rst 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_source/mitK5license.rst 2012-03-28 02:03:33 UTC (rev 25791)
@@ -3,5 +3,5 @@
MIT Kerberos License information
================================
-.. include:: ../../NOTICE
+.. include:: NOTICE
:literal:
Modified: trunk/doc/rst_source/relay/build_this.rst
===================================================================
--- trunk/doc/rst_source/relay/build_this.rst 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_source/relay/build_this.rst 2012-03-28 02:03:33 UTC (rev 25791)
@@ -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
Modified: trunk/doc/rst_tools/define_document.tmpl
===================================================================
--- trunk/doc/rst_tools/define_document.tmpl 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_tools/define_document.tmpl 2012-03-28 02:03:33 UTC (rev 25791)
@@ -14,8 +14,6 @@
-:krb5doxy:`Doxygen reference to $composite.name <$composite.name>`
-
..
.. data:: $composite.name
..
Modified: trunk/doc/rst_tools/func_document.tmpl
===================================================================
--- trunk/doc/rst_tools/func_document.tmpl 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_tools/func_document.tmpl 2012-03-28 02:03:33 UTC (rev 25791)
@@ -6,8 +6,6 @@
$title
#echo ''.join(['=']*len($title)) #
-:krb5doxy:`Doxygen reference to $function.name <$function.name>`
-
..
.. c:function:: $signature
Modified: trunk/doc/rst_tools/type_document.tmpl
===================================================================
--- trunk/doc/rst_tools/type_document.tmpl 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/doc/rst_tools/type_document.tmpl 2012-03-28 02:03:33 UTC (rev 25791)
@@ -14,8 +14,6 @@
-:krb5doxy:`Doxygen reference to $composite.name <$composite.name>`
-
..
.. c:type:: $composite.name
..
Modified: trunk/src/Makefile.in
===================================================================
--- trunk/src/Makefile.in 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/src/Makefile.in 2012-03-28 02:03:33 UTC (rev 25791)
@@ -773,10 +773,3 @@
(cd $(top_srcdir) && \
$(FIND) . \( -name '*.[ch]' -o -name '*.hin' \) -print0 | \
$(XARGS) -0 python util/krb5-check-copyright.py)
-
-doxygen::
- if test "which doxygen" != ""; then \
- doxygen; \
- else \
- echo "Doxygen is not installed or incorrect PATH"; \
- fi
Added: trunk/src/doc/Doxyfile.in
===================================================================
--- trunk/src/doc/Doxyfile.in (rev 0)
+++ trunk/src/doc/Doxyfile.in 2012-03-28 02:03:33 UTC (rev 25791)
@@ -0,0 +1,14 @@
+PROJECT_NAME = Kerberos_doxygen
+OUTPUT_DIRECTORY = doxy
+JAVADOC_AUTOBRIEF = YES
+OPTIMIZE_OUTPUT_FOR_C = YES
+WARN_IF_UNDOCUMENTED = NO
+SHOW_FILES = NO
+INPUT = @SRC@/include/krb5/krb5.hin @DOC@/doxy_examples
+EXAMPLE_PATH = @DOC@/doxy_examples
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+GENERATE_XML = YES
+PREDEFINED = KRB5_DEPRECATED KRB5_OLD_CRYPTO
+CLASS_DIAGRAMS = NO
+CASE_SENSE_NAMES = NO
Modified: trunk/src/doc/Makefile.in
===================================================================
--- trunk/src/doc/Makefile.in 2012-03-27 02:32:57 UTC (rev 25790)
+++ trunk/src/doc/Makefile.in 2012-03-28 02:03:33 UTC (rev 25791)
@@ -2,6 +2,7 @@
BUILDTOP=$(REL)..
SPHINX_BUILD=sphinx-build
+DOXYGEN=doxygen
docsrc=$(top_srcdir)/../doc
mansrc=$(top_srcdir)/man
@@ -16,5 +17,34 @@
sed -e '/^\.\\" $$/d' $$f > $(mansrc)/$$name.man; \
done
+# Create HTML documentation in $(docsrc)/rst_html suitable for a
+# release tarball or the web site (that is, without substitutions for
+# configured paths). This can be done in an unconfigured source tree
+# with:
+# make -f Makefile.in top_srcdir=.. PYTHON=python rsthml
+# make -f Makefile.in clean
+rsthtml: composite
+ rm -rf $(docsrc)/rst_html
+ $(SPHINX_BUILD) -q rst_composite $(docsrc)/rst_html
+
+# 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.
+composite: Doxyfile
+ rm -rf doxy rst_apiref rst_composite
+ $(DOXYGEN)
+ cwd=`pwd`; cd $(docsrc)/rst_tools && \
+ $(PYTHON) doxy.py -i $$cwd/doxy/xml -o $$cwd/rst_apiref
+ cp -r $(docsrc)/rst_source rst_composite
+ cp rst_apiref/*.rst rst_composite/krb_appldev/refs/api
+ cp rst_apiref/types/*.rst rst_composite/krb_appldev/refs/types
+ cp rst_apiref/macros/*.rst rst_composite/krb_appldev/refs/macros
+ cp $(top_srcdir)/../NOTICE rst_composite
+
+Doxyfile: $(srcdir)/Doxyfile.in
+ sed -e 's|@SRC@|$(top_srcdir)|g' \
+ -e 's|@DOC@|$(top_srcdir)/../doc|g' $(srcdir)/Doxyfile.in > $@
+
clean::
- $(RM) -r mantmp
+ rm -rf rst_man doxy rst_apiref rst_composite Doxyfile
More information about the cvs-krb5
mailing list