[prev in list] [next in list] [prev in thread] [next in thread]
List: krb5-cvs
Subject: svn rev #25423: trunk/doc/rst_source/relay/
From: tsitkova () mit ! edu
Date: 2011-10-30 21:52:18
Message-ID: 201110302152.p9ULqIje007719 () drugstore ! mit ! edu
[Download RAW message or body]
http://src.mit.edu/fisheye/changelog/krb5/?cs=25423
Commit By: tsitkova
Log Message:
Added instruction on how to build this Sphinx documentation
Changed Files:
A trunk/doc/rst_source/relay/build_this.rst
U trunk/doc/rst_source/relay/index.rst
A trunk/doc/rst_source/relay/philosophy.rst
Added: trunk/doc/rst_source/relay/build_this.rst
===================================================================
--- trunk/doc/rst_source/relay/build_this.rst (rev 0)
+++ trunk/doc/rst_source/relay/build_this.rst 2011-10-30 21:52:18 UTC (rev 25423)
@@ -0,0 +1,124 @@
+How to build this documentation from the source
+==================================================
+
+Pre-requisites:
+
+ - Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with "autodoc" extension \
installed. +
+
+How to build the Sphinx based documentation without references to API documentation
+---------------------------------------------------------------------------------------
+
+To generate documentation in the *html* format, from the *trunk/doc/rst_source* \
run:: +
+ sphinx-build . output_dir
+
+To produce manpages run::
+
+ sphinx-build -b man . output_dir
+
+.. note:: The manpages output is controled by *man_pages* tag in the Sphinx \
configuration file + *trunk/doc/rst_source/conf.py*.
+
+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.
+
+Pre-requisites:
+
+ - 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
+
+.. _Part_A:
+
+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* located in trunk/doc/rst_tools \
directory; +
+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::
+
+ 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 the *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.
+
+
+
Modified: trunk/doc/rst_source/relay/index.rst
===================================================================
--- trunk/doc/rst_source/relay/index.rst 2011-10-28 16:18:45 UTC (rev 25422)
+++ trunk/doc/rst_source/relay/index.rst 2011-10-30 21:52:18 UTC (rev 25423)
@@ -1,39 +1,10 @@
-Kerberos Documentation Relay
-=======================================
+.. toctree::
+ :maxdepth: 1
-Philosophy.
------------
+ philosophy.rst
+ build_this.rst
-#. The documentation must be useful;
-#. The documentation must be correct;
-
-#. The documentation must be detailed, but optimized. No verbose mode;
-
-#. The documentation should be built incrementally;
-
-#. The documentation should be easy to maintain;
-
-#. The documentation should be examined to identify the approaches that do not work;
-
-
-
-Process.
-------------
-
-#. The Work-To-Do list is created and updated based on the input from the community.
-#. Administrator supports the Work-To-Do list.
-#. Writer picks up the item from this list (such as specific API) and writes the \
documentation
-#. Committee reviews the documentation and recommends it to be accepted as-is or to \
be revised
-#. If the documentation needs revision, it is sent to the initial writer or someone \
else for completion
-#. Once Committee approves the document, it is proofread by the designated engineer
-#. Documented is posted on the web
-
-Feedback and Comments.
-------------------------
-
-At the moment the comments should be sent via email to krb5-bugs@mit.edu. Normally, \
every document has an email link with the pre-constructed subject line similar to the \
following:
-
Please, provide your feedback on this document at \
krb5-bugs@mit.edu?subject=Documentation___relay_feedback
Added: trunk/doc/rst_source/relay/philosophy.rst
===================================================================
--- trunk/doc/rst_source/relay/philosophy.rst (rev 0)
+++ trunk/doc/rst_source/relay/philosophy.rst 2011-10-30 21:52:18 UTC (rev 25423)
@@ -0,0 +1,39 @@
+Kerberos Documentation Relay
+=======================================
+
+
+Philosophy.
+-----------
+
+#. The documentation must be useful;
+
+#. The documentation must be correct;
+
+#. The documentation must be detailed, but optimized. No verbose mode;
+
+#. The documentation should be built incrementally;
+
+#. The documentation should be easy to maintain;
+
+#. The documentation should be examined to identify the approaches that do not work;
+
+
+
+Process.
+------------
+
+#. The Work-To-Do list is created and updated based on the input from the community.
+#. Administrator supports the Work-To-Do list.
+#. Writer picks up the item from this list (such as specific API) and writes the \
documentation +#. Committee reviews the documentation and recommends it to be \
accepted as-is or to be revised +#. If the documentation needs revision, it is sent \
to the initial writer or someone else for completion +#. Once Committee approves the \
document, it is proofread by the designated engineer +#. Documented is posted on the \
web +
+Feedback and Comments.
+------------------------
+
+At the moment the comments should be sent via email to krb5-bugs@mit.edu. Normally, \
every document has an email link with the pre-constructed subject line similar to the \
following: +
+Please, provide your feedback on this document at \
krb5-bugs@mit.edu?subject=Documentation___relay_feedback +
_______________________________________________
cvs-krb5 mailing list
cvs-krb5@mit.edu
https://mailman.mit.edu/mailman/listinfo/cvs-krb5
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic