summaryrefslogtreecommitdiffstats
path: root/doc/build_this.rst
blob: d31ee232bcc822573b486fd7efd5fda23b8d69d3 (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
How to build this documentation from the source
===============================================

Pre-requisites for a simple build, or to update man pages:

* Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with the autodoc
  extension installed.

Additional prerequisites to include the API reference based on Doxygen
markup:

* Python 2.5 with the Cheetah, lxml, and xml modules
* Doxygen


Simple build without API reference
----------------------------------

To test simple changes to the RST sources, you can build the
documentation without the Doxygen reference by running, from the doc
directory::

    sphinx-build . test_html

You will see a number of warnings about missing files.  This is
expected.


Updating man pages
------------------

Man pages are generated from the RST sources and checked into the
``src/man`` directory of the repository.  This allows man pages to be
installed without requiring Sphinx when using a source checkout.  To
regenerate these files, run ``make man`` from the man subdirectory
of a configured build tree.  You can also do this from an unconfigured
source tree with::

    cd src/man
    make -f Makefile.in top_srcdir=.. srcdir=. man
    make clean

As with the simple build, it is normal to see warnings about missing
files when rebuilding the man pages.


Building for a release tarball or web site
------------------------------------------

To generate documentation in HTML format, run ``make html`` in the
``doc`` subdirectory of a configured build tree (the build directory
corresponding to ``src/doc``, not the top-level ``doc`` directory).
The output will be placed in the top-level ``doc/html`` directory.
This build will include the API reference generated from Doxygen
markup in the source tree.

Documentation generated this way will use symbolic names for paths
(like ``BINDIR`` for the directory containing user programs), with the
symbolic names being links to a table showing typical values for those
paths.

You can also do this from an unconfigured source tree with::

    cd src/doc
    make -f Makefile.in SPHINX_ARGS= htmlsrc


Building for an OS package or site documentation
------------------------------------------------

To generate documentation specific to a build of MIT krb5 as you have
configured it, run ``make substhtml`` in the ``doc`` subdirectory of a
configured build tree (the build directory corresponding to
``src/doc``, not the top-level ``doc`` directory).  The output will be
placed in the ``html_subst`` subdirectory of that build directory.
This build will include the API reference.

Documentation generated this way will use concrete paths (like
``/usr/local/bin`` for the directory containing user programs, for a
default custom build).