"Fossies" - the Fresh Open Source Software Archive

Member "krb5-1.18/doc/tools/README" (12 Feb 2020, 2726 Bytes) of package /linux/misc/krb5-1.18.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 How to deploy the Doxygen output in Sphinx project.
    2 ====================================================
    3 
    4 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.
    5 
    6 Pre-requisites:
    7 - python 2.5+ with Cheetah, lxml and  xml extension modules installed;
    8 - For part B only:
    9     -    Sphinx "doxylink" extension;
   10     -    Doxygen HTML output
   11 
   12 
   13 Part A:    Transforming Doxygen XML output into reStructuredText (rst)  without the bridge to Doxygen HTML output.
   14 
   15 1.    Delete lines containing text "Doxygen reference" from the template files func_document.tmpl and type_document.tmpl;
   16 
   17 2.    In the Doxygen configuration file set GENERATE_XML to YES. Generate Doxygen XML output;
   18 
   19 3.    Suppose the Doxygen XML output is located in doxy_xml_dir  and the desired output directory is rst_dir.
   20       Run:
   21       python doxy.py -i  doxy_xml_dir -o rst_dir -t func
   22       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
   23 
   24       Run:
   25       python doxy.py -i  doxy_xml_dir -o rst_dir -t typedef
   26       It is similar to the API function conversion, but for data types. The result will be stored under rst_dir/types directory
   27 
   28       Alternatively, running
   29       python doxy.py -i  doxy_xml_dir -o rst_dir
   30       or
   31       python doxy.py -i  doxy_xml_dir -o rst_dir -t all
   32       converts Doxygen XML output into reStructuredText format files both for API functions and data types;
   33 
   34 4.    In appdev/index.rst add the following section to point to the API references:
   35 
   36       .. toctree::
   37           :maxdepth: 1
   38 
   39           refs/index.rst
   40 
   41 5.    Copy the content of rst_dir into appdev/refs/api/ directory and rst_dir/types into appdev/refs/types directory;
   42 
   43 6.    Rebuild Sphinx source:
   44       sphinx-build source_dir build_dir
   45 
   46 
   47 
   48 
   49 Part B:    Bridge to Doxygen HTML output.
   50 
   51 1. Transform Doxygen XML output into reStructuredText.
   52    In src/Doxygen configuration file request generation of the tag file and XML output:
   53        GENERATE_TAGFILE       = krb5doxy.tag
   54        GENERATE_XML           = YES
   55 
   56 2. Modify Sphinx conf.py file to point to the "doxylink" extension and Doxygen tag file:
   57       extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
   58       doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') }
   59 
   60    where doxy_html_dir is the location of the Doxygen HTML output
   61 
   62 3.  Continue with steps 3 - 6 of Part A.