Add a 'Install prerequisites' chapter and updated the 'Sphinx build' chapter. Signed-off-by: Markus Heiser <markus.heiser@xxxxxxxxxxx> --- Documentation/kernel-documentation.rst | 83 ++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 9 deletions(-) diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index 10cc7dd..2891f7f 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -31,22 +31,87 @@ over time, but the bulk of them will remain in plain text. Sphinx Build ============ -The usual way to generate the documentation is to run ``make htmldocs`` or -``make pdfdocs``. There are also other formats available, see the documentation -section of ``make help``. The generated documentation is placed in -format-specific subdirectories under ``Documentation/output``. +The usual way to generate the documentation is to run:: -To generate documentation, Sphinx (``sphinx-build``) must obviously be -installed. For prettier HTML output, the Read the Docs Sphinx theme -(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also -needed. All of these are widely available and packaged in distributions. + make htmldocs + +There are also other formats available, see the documentation section of ``make +help``. The generated documentation is placed in format-specific subdirectories +under ``Documentation/output``. To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose -output. +output or to build with nit-picky mode use ``make SPHINXOPTS=-n htmldocs``. + +With ``make htmldocs``, the HTML of the DocBook content is also build, if you +don't want so, set ``DOCBOOKS=`` option empty:: + + make DOCBOOKS= htmldocs To remove the generated documentation, run ``make cleandocs``. +To build only a specific subdirectory of the sphinx content use make variable +``SPHINXDIRS=<subdir>``. To build e.g. the gpu documentation stand-alone run:: + + make DOCBOOKS= SPHINXDIRS=gpu htmldocs + +There are also other formats available, see the documentation section of ``make +help`` and prerequisite_. The generated documentation is placed in +format-specific subdirectories. + +.. _prerequisite: + +Install prerequisites +===================== + +To generate documentation, Sphinx (``sphinx-build``) must obviously be +installed. For prettier HTML output, the Read the Docs Sphinx theme +(``sphinx_rtd_theme``) is used if available. All of these are widely available +and packaged in distributions. + +Debian/Ubuntu:: + + apt-get install python3-sphinx python3-sphinx-rtd-theme + +Fedora:: + + yum install python3-sphinx-rtd-theme python3-sphinx-rtd-theme + +If you don't have *admin* privileges, use pip3 (or even pip) for a local user +installation:: + + $ pip3 install --user Sphinx sphinx_rtd_theme + +Until here, you have installed the minimum requirements to build HTML output +which might be good enough for most use cases. If you want more from your +sphinx-build, you have to install the following (optional) prerequisites. + +For PDF output and *Math support* (nicely rendered mathematical notations) a +LaTeX tool-chain is required. + +Debian/Ubuntu:: + + apt-get install \ + texlive-base texlive-xetex texlive-latex-recommended \ + texlive-extra-utils dvipng ttf-dejavu + +Fedora:: + + yum install \ + texlive-amsmath.noarch texlive-mathtools.noarch + texlive-anyfontsize.noarch texlive-xelatex + texlive-xetex texlive-xecolor.noarch + texlive-titlesec.noarch texlive-framed texlive-threeparttable + texlive-wrapfig texlive-upquote texlive-capt-of eqparbox + +Further reading: + +* `RTD theme <https://pypi.python.org/pypi/sphinx_rtd_theme>`_ +* `TeX Live <https://www.tug.org/texlive>`_ +* `Math support in Sphinx <http://www.sphinx-doc.org/ext/math.html>`_ +* `dvisvgm (A fast DVI to SVG converter) <http://dvisvgm.bplaced.net/Downloads>`_ + + Writing Documentation ===================== -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
