1How to build this documentation from the source
2===============================================
3
4Pre-requisites for a simple build, or to update man pages:
5
6* Sphinx 1.0.4 or higher (See https://www.sphinx-doc.org) with the
7  autodoc extension installed.
8
9Additional prerequisites to include the API reference based on Doxygen
10markup:
11
12* Python 2.5 with the Cheetah, lxml, and xml modules
13* Doxygen
14
15
16Simple build without API reference
17----------------------------------
18
19To test simple changes to the RST sources, you can build the
20documentation without the Doxygen reference by running, from the doc
21directory::
22
23    sphinx-build . test_html
24
25You will see a number of warnings about missing files.  This is
26expected.  If there is not already a ``doc/version.py`` file, you will
27need to create one by first running ``make version.py`` in the
28``src/doc`` directory of a configured build tree.
29
30
31Updating man pages
32------------------
33
34Man pages are generated from the RST sources and checked into the
35``src/man`` directory of the repository.  This allows man pages to be
36installed without requiring Sphinx when using a source checkout.  To
37regenerate these files, run ``make man`` from the man subdirectory
38of a configured build tree.  You can also do this from an unconfigured
39source tree with::
40
41    cd src/man
42    make -f Makefile.in top_srcdir=.. srcdir=. man
43    make clean
44
45As with the simple build, it is normal to see warnings about missing
46files when rebuilding the man pages.
47
48
49Building for a release tarball or web site
50------------------------------------------
51
52To generate documentation in HTML format, run ``make html`` in the
53``doc`` subdirectory of a configured build tree (the build directory
54corresponding to ``src/doc``, not the top-level ``doc`` directory).
55The output will be placed in the top-level ``doc/html`` directory.
56This build will include the API reference generated from Doxygen
57markup in the source tree.
58
59Documentation generated this way will use symbolic names for paths
60(like ``BINDIR`` for the directory containing user programs), with the
61symbolic names being links to a table showing typical values for those
62paths.
63
64You can also do this from an unconfigured source tree with::
65
66    cd src/doc
67    make -f Makefile.in SPHINX_ARGS= htmlsrc
68
69
70Building for an OS package or site documentation
71------------------------------------------------
72
73To generate documentation specific to a build of MIT krb5 as you have
74configured it, run ``make substhtml`` in the ``doc`` subdirectory of a
75configured build tree (the build directory corresponding to
76``src/doc``, not the top-level ``doc`` directory).  The output will be
77placed in the ``html_subst`` subdirectory of that build directory.
78This build will include the API reference.
79
80Documentation generated this way will use concrete paths (like
81``/usr/local/bin`` for the directory containing user programs, for a
82default custom build).
83