How to build this documentation from the source — MIT Kerberos Documentation

# MIT Kerberos Documentation

Contents | previous | next | index | Search | feedback

# 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 https://www.sphinx-doc.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. If there is not already a `doc/version.py` file, you will need to create one by first running `make version.py` in the `src/doc` directory of a configured build tree.

## 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).