svn rev #24997: trunk/doc/rst_tools/

[tsitkova@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=24997
Commit By: tsitkova
Log Message:
Add instructions for adding the API reference documentation to Sphinx Kerberos documentation project



Changed Files:
A   trunk/doc/rst_tools/README
U   trunk/doc/rst_tools/docmodel.py
U   trunk/doc/rst_tools/func_document.tmpl
U   trunk/doc/rst_tools/type_document.tmpl
Added: trunk/doc/rst_tools/README
===================================================================
--- trunk/doc/rst_tools/README	                        (rev 0)
+++ trunk/doc/rst_tools/README	2011-06-28 17:36:52 UTC (rev 24997)
@@ -0,0 +1,61 @@
+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 with (Part B) or without (Part A) the bridge to the original Doxygen HTML output.
+
+Pre-requisites:
+- python 2.5+ with Cheetah, lxml and  xml extension modules installed;
+- For part B only:
+    -    Sphinx “doxylink” extension;
+    -    Doxygen HTML output
+
+
+Part A:    Transforming Doxygen XML output into reStructuredText (rst)  without the bridge to Doxygen HTML output.
+
+1.    Delete lines containing text "Doxygen reference" from the template files func_document.tmpl and type_document.tmpl;
+
+2.    In the Doxygen configuration file set GENERATE_XML to YES. Generate Doxygen XML output;
+
+3.    Suppose the Doxygen XML output is located in doxy_xml_dir  and the desired output directory is rst_dir.
+      Run:
+      python doxy.py –i  doxy_xml_dir –o rst_dir –t func
+      This will result in the storing of the API function documentation files in rst format in the rst_dir. 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  doxy_xml_dir –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  doxy_xml_dir –o rst_dir
+      or
+      python doxy.py –i  doxy_xml_dir –o rst_dir -t all
+      converts Doxygen XML output into reStructuredText format files both for API functions and data types;
+
+4.    In 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:
+      sphinx-build source_dir build_dir
+
+
+
+
+Part B:    Transforming Doxygen XML output into reStructuredText with the bridge to Doxygen HTML output.
+
+1.   In the Doxygen configuration file set option GENERATE_XML to YES. Also, set option GENERATE_TAGFILE to create a Doxygen tag file. For example, GENERATE_TAGFILE = /tmp/krb5doxy.tag. Generate Doxygen XML output;
+
+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.
+

Modified: trunk/doc/rst_tools/docmodel.py
===================================================================
--- trunk/doc/rst_tools/docmodel.py	2011-06-28 14:07:07 UTC (rev 24996)
+++ trunk/doc/rst_tools/docmodel.py	2011-06-28 17:36:52 UTC (rev 24997)
@@ -1,7 +1,25 @@
 '''
-Created on Nov 9, 2010
+  Copyright 2011 by the Massachusetts
+  Institute of Technology.  All Rights Reserved.
 
- at author: tsitkova
+  Export of this software from the United States of America may
+  require a specific license from the United States Government.
+  It is the responsibility of any person or organization contemplating
+  export to obtain such a license before exporting.
+
+  WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
+  distribute this software and its documentation for any purpose and
+  without fee is hereby granted, provided that the above copyright
+  notice appear in all copies and that both that copyright notice and
+  this permission notice appear in supporting documentation, and that
+  the name of M.I.T. not be used in advertising or publicity pertaining
+  to distribution of the software without specific, written prior
+  permission.  Furthermore if you modify this software you must label
+  your software as modified software and not distribute it in such a
+  fashion that it might be confused with the original M.I.T. software.
+  M.I.T. makes no representations about the suitability of
+  this software for any purpose.  It is provided "as is" without express
+  or implied warranty.
 '''
 import re
 

Modified: trunk/doc/rst_tools/func_document.tmpl
===================================================================
--- trunk/doc/rst_tools/func_document.tmpl	2011-06-28 14:07:07 UTC (rev 24996)
+++ trunk/doc/rst_tools/func_document.tmpl	2011-06-28 17:36:52 UTC (rev 24997)
@@ -6,7 +6,7 @@
 $title
 #echo ''.join(['=']*len($title)) #
 
-:polyvox:`Doxygen reference to $function.name  <$function.name>`
+:krb5doxy:`Doxygen reference to $function.name  <$function.name>`
 
 ..
 

Modified: trunk/doc/rst_tools/type_document.tmpl
===================================================================
--- trunk/doc/rst_tools/type_document.tmpl	2011-06-28 14:07:07 UTC (rev 24996)
+++ trunk/doc/rst_tools/type_document.tmpl	2011-06-28 17:36:52 UTC (rev 24997)
@@ -14,7 +14,7 @@
 
 
 
-:polyvox:`Doxygen reference to $composite.name  <$composite.name>`
+:krb5doxy:`Doxygen reference to $composite.name  <$composite.name>`
 
 ..
 .. c:type:: $composite.name