MIT rst tools ¶

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 :

Transforming Doxygen XML output into reStructuredText (rst) without the bridge to Doxygen HTML output.

Delete lines containing text “Doxygen reference” from the template files func_document.tmpl and type_document.tmpl;
In the Doxygen configuration file set GENERATE_XML to YES. Generate Doxygen XML output;
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;
In krb_appldev/index.rst add the following section to point to the API references:
```
.. toctree::
    :maxdepth: 1

    refs/index.rst
```
Copy the content of rst_dir into krb_appldev/refs/api/ directory and rst_dir/types into krb_appldev/refs/types directory;
Rebuild Sphinx source:
```
sphinx-build source_dir build_dir
```