doc/rst_source/relay/build_this.rst

   1 How to build this documentation from the source
   2 ===============================================
   3
   4 Pre-requisites for the simple build, or to update man pages:
   5
   6 * Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc”
   7   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 rst_source test_html
  24
  25 You will see a number of warnings about missing files.  This is
  26 expected.
  27
  28
  29 Updating man pages
  30 ------------------
  31
  32 Man pages are generated from the RST sources and checked into the
  33 ``src/man`` directory of the repository.  This allows man pages to be
  34 installed without requiring Sphinx when using a source checkout.  To
  35 regenerate these files, run ``make rstman`` from the man subdirectory
  36 of a configured build tree.  You can also do this from an unconfigured
  37 source tree with::
  38
  39     cd src/man
  40     make -f Makefile.in top_srcdir=.. srcdir=. rstman
  41     make clean
  42
  43 As with the simple build, it is normal to see warnings about missing
  44 files when rebuilding the man pages.
  45
  46
  47 Building for a release tarball or web site
  48 ------------------------------------------
  49
  50 To generate documentation in HTML format, run ``make rsthtml`` in the
  51 ``doc`` subdirectory of a configured build tree (the build directory
  52 corresponding to ``src/doc``, not the top-level ``doc`` directory).
  53 The output will be placed in the top-level ``doc/rst_html`` directory.
  54 This build will include the API reference generated from Doxygen
  55 markup in the source tree.
  56
  57 Documentation generated this way will use symbolic names for paths
  58 (like ``BINDIR`` for the directory containing user programs), with the
  59 symbolic names being links to a table showing typical values for those
  60 paths.
  61
  62 You can also do this from an unconfigured source tree with::
  63
  64     cd src/doc
  65     make -f Makefile.in top_srcdir=.. PYTHON=python rsthml
  66     make -f Makefile.in clean
  67
  68
  69 Building for an OS package or site documentation
  70 ------------------------------------------------
  71
  72 To generate documentation specific to a build of MIT krb5 as you have
  73 configured it, run ``make substhtml`` in the ``doc`` subdirectory of a
  74 configured build tree (the build directory corresponding to
  75 ``src/doc``, not the top-level ``doc`` directory).  The output will be
  76 placed in the ``rst_html_subst`` subdirectory of that build directory.
  77 This build will include the API reference.
  78
  79 Documentation generated this way will use concrete paths (like
  80 ``/usr/local/bin`` for the directory containing user programs, for a
  81 default custom build).