1*7f2fe78bSCy SchubertHow to build this documentation from the source 2*7f2fe78bSCy Schubert=============================================== 3*7f2fe78bSCy Schubert 4*7f2fe78bSCy SchubertPre-requisites for a simple build, or to update man pages: 5*7f2fe78bSCy Schubert 6*7f2fe78bSCy Schubert* Sphinx 1.0.4 or higher (See https://www.sphinx-doc.org) with the 7*7f2fe78bSCy Schubert autodoc extension installed. 8*7f2fe78bSCy Schubert 9*7f2fe78bSCy SchubertAdditional prerequisites to include the API reference based on Doxygen 10*7f2fe78bSCy Schubertmarkup: 11*7f2fe78bSCy Schubert 12*7f2fe78bSCy Schubert* Python 2.5 with the Cheetah, lxml, and xml modules 13*7f2fe78bSCy Schubert* Doxygen 14*7f2fe78bSCy Schubert 15*7f2fe78bSCy Schubert 16*7f2fe78bSCy SchubertSimple build without API reference 17*7f2fe78bSCy Schubert---------------------------------- 18*7f2fe78bSCy Schubert 19*7f2fe78bSCy SchubertTo test simple changes to the RST sources, you can build the 20*7f2fe78bSCy Schubertdocumentation without the Doxygen reference by running, from the doc 21*7f2fe78bSCy Schubertdirectory:: 22*7f2fe78bSCy Schubert 23*7f2fe78bSCy Schubert sphinx-build . test_html 24*7f2fe78bSCy Schubert 25*7f2fe78bSCy SchubertYou will see a number of warnings about missing files. This is 26*7f2fe78bSCy Schubertexpected. If there is not already a ``doc/version.py`` file, you will 27*7f2fe78bSCy Schubertneed to create one by first running ``make version.py`` in the 28*7f2fe78bSCy Schubert``src/doc`` directory of a configured build tree. 29*7f2fe78bSCy Schubert 30*7f2fe78bSCy Schubert 31*7f2fe78bSCy SchubertUpdating man pages 32*7f2fe78bSCy Schubert------------------ 33*7f2fe78bSCy Schubert 34*7f2fe78bSCy SchubertMan pages are generated from the RST sources and checked into the 35*7f2fe78bSCy Schubert``src/man`` directory of the repository. This allows man pages to be 36*7f2fe78bSCy Schubertinstalled without requiring Sphinx when using a source checkout. To 37*7f2fe78bSCy Schubertregenerate these files, run ``make man`` from the man subdirectory 38*7f2fe78bSCy Schubertof a configured build tree. You can also do this from an unconfigured 39*7f2fe78bSCy Schubertsource tree with:: 40*7f2fe78bSCy Schubert 41*7f2fe78bSCy Schubert cd src/man 42*7f2fe78bSCy Schubert make -f Makefile.in top_srcdir=.. srcdir=. man 43*7f2fe78bSCy Schubert make clean 44*7f2fe78bSCy Schubert 45*7f2fe78bSCy SchubertAs with the simple build, it is normal to see warnings about missing 46*7f2fe78bSCy Schubertfiles when rebuilding the man pages. 47*7f2fe78bSCy Schubert 48*7f2fe78bSCy Schubert 49*7f2fe78bSCy SchubertBuilding for a release tarball or web site 50*7f2fe78bSCy Schubert------------------------------------------ 51*7f2fe78bSCy Schubert 52*7f2fe78bSCy SchubertTo generate documentation in HTML format, run ``make html`` in the 53*7f2fe78bSCy Schubert``doc`` subdirectory of a configured build tree (the build directory 54*7f2fe78bSCy Schubertcorresponding to ``src/doc``, not the top-level ``doc`` directory). 55*7f2fe78bSCy SchubertThe output will be placed in the top-level ``doc/html`` directory. 56*7f2fe78bSCy SchubertThis build will include the API reference generated from Doxygen 57*7f2fe78bSCy Schubertmarkup in the source tree. 58*7f2fe78bSCy Schubert 59*7f2fe78bSCy SchubertDocumentation generated this way will use symbolic names for paths 60*7f2fe78bSCy Schubert(like ``BINDIR`` for the directory containing user programs), with the 61*7f2fe78bSCy Schubertsymbolic names being links to a table showing typical values for those 62*7f2fe78bSCy Schubertpaths. 63*7f2fe78bSCy Schubert 64*7f2fe78bSCy SchubertYou can also do this from an unconfigured source tree with:: 65*7f2fe78bSCy Schubert 66*7f2fe78bSCy Schubert cd src/doc 67*7f2fe78bSCy Schubert make -f Makefile.in SPHINX_ARGS= htmlsrc 68*7f2fe78bSCy Schubert 69*7f2fe78bSCy Schubert 70*7f2fe78bSCy SchubertBuilding for an OS package or site documentation 71*7f2fe78bSCy Schubert------------------------------------------------ 72*7f2fe78bSCy Schubert 73*7f2fe78bSCy SchubertTo generate documentation specific to a build of MIT krb5 as you have 74*7f2fe78bSCy Schubertconfigured it, run ``make substhtml`` in the ``doc`` subdirectory of a 75*7f2fe78bSCy Schubertconfigured build tree (the build directory corresponding to 76*7f2fe78bSCy Schubert``src/doc``, not the top-level ``doc`` directory). The output will be 77*7f2fe78bSCy Schubertplaced in the ``html_subst`` subdirectory of that build directory. 78*7f2fe78bSCy SchubertThis build will include the API reference. 79*7f2fe78bSCy Schubert 80*7f2fe78bSCy SchubertDocumentation generated this way will use concrete paths (like 81*7f2fe78bSCy Schubert``/usr/local/bin`` for the directory containing user programs, for a 82*7f2fe78bSCy Schubertdefault custom build). 83