blob: c8b29bc8627b1652231cbef8ef773baf1733dfa5 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
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.
|
