Em Sun, 23 Oct 2016 17:18:02 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > Add a 'Install prerequisites' chapter and updated the 'Sphinx build' chapter. Hmm... IMO, 'Install prerequisites' should be at Documentation/Changes. Btw, I added that already, on one of my patches (pending merge): https://patchwork.kernel.org/patch/9339021/ We use Documentation/Changes for all build and runtime requirements. Of course, it doesn't hurt to have a cross-reference, or to have a quick summary, but I would keep the more detailed info there. > > 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. IMHO, you should mention the usage of SPHINXOPTS="-j11" parameter, explaining that the number of threads depend on the system. Here, my 4 CPU desktop works best with -j4, but my 16 CPU server gets best results with -j11. > + > +.. _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>`_ > + > + Ad mentioned, IMHO, the above should be at Changes. > Writing Documentation > ===================== > Thanks, Mauro -- 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
