doc/build_this.rst

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