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