From 56f47810be476764db26a68f071cb0ddd8a325fd Mon Sep 17 00:00:00 2001 From: Zhanna Tsitkov Date: Sun, 30 Oct 2011 21:52:18 +0000 Subject: [PATCH] Added instruction on how to build this Sphinx documentation git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25423 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/relay/build_this.rst | 124 ++++++++++++++++++++++++++++ doc/rst_source/relay/index.rst | 37 +-------- doc/rst_source/relay/philosophy.rst | 39 +++++++++ 3 files changed, 167 insertions(+), 33 deletions(-) create mode 100644 doc/rst_source/relay/build_this.rst create mode 100644 doc/rst_source/relay/philosophy.rst diff --git a/doc/rst_source/relay/build_this.rst b/doc/rst_source/relay/build_this.rst new file mode 100644 index 000000000..c8b29bc86 --- /dev/null +++ b/doc/rst_source/relay/build_this.rst @@ -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. + + + diff --git a/doc/rst_source/relay/index.rst b/doc/rst_source/relay/index.rst index 3a0e219f9..6d3ae03c5 100644 --- a/doc/rst_source/relay/index.rst +++ b/doc/rst_source/relay/index.rst @@ -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 diff --git a/doc/rst_source/relay/philosophy.rst b/doc/rst_source/relay/philosophy.rst new file mode 100644 index 000000000..3a0e219f9 --- /dev/null +++ b/doc/rst_source/relay/philosophy.rst @@ -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 + -- 2.26.2