diff options
Diffstat (limited to 'doc/usage/builders')
| -rw-r--r-- | doc/usage/builders/index.rst | 71 |
1 files changed, 62 insertions, 9 deletions
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index ce2c5dc..9c538ee 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -10,9 +10,62 @@ Builders These are the built-in Sphinx builders. More builders can be added by :doc:`extensions </usage/extensions/index>`. -The builder's "name" must be given to the **-b** command-line option of +The builder's "name" must be given to the **-M** or **-b** command-line options of :program:`sphinx-build` to select a builder. +The most common builders are: + +**html** + Build HTML pages. This is the default builder. + +**dirhtml** + Build HTML pages, but with a single directory per document. Makes for + prettier URLs (no ``.html``) if served from a webserver. + +**singlehtml** + Build a single HTML with the whole content. + +**htmlhelp**, **qthelp**, **devhelp**, **epub** + Build HTML files with additional information for building a documentation + collection in one of these formats. + +**applehelp** + Build an Apple Help Book. Requires :program:`hiutil` and + :program:`codesign`, which are not Open Source and presently only + available on Mac OS X 10.6 and higher. + +**latex** + Build LaTeX sources that can be compiled to a PDF document using + :program:`pdflatex`. + +**man** + Build manual pages in groff format for UNIX systems. + +**texinfo** + Build Texinfo files that can be processed into Info files using + :program:`makeinfo`. + +**text** + Build plain text files. + +**gettext** + Build gettext-style message catalogs (``.pot`` files). + +**doctest** + Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest` + extension is enabled. + +**linkcheck** + Check the integrity of all external links. + +**xml** + Build Docutils-native XML files. + +**pseudoxml** + Build compact pretty-printed "pseudo-XML" files displaying the + internal structure of the intermediate document trees. + +-------------- .. module:: sphinx.builders.html .. class:: StandaloneHTMLBuilder @@ -146,7 +199,7 @@ The builder's "name" must be given to the **-b** command-line option of This builder produces the same output as the standalone HTML builder, but also generates an *epub* file for ebook readers. See :ref:`epub-faq` for details about it. For definition of the epub format, have a look at - `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_. + `<https://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_. The builder creates *EPUB 3* files. .. autoattribute:: name @@ -300,8 +353,8 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. class:: SerializingHTMLBuilder This builder uses a module that implements the Python serialization API - (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated - HTML documentation. The pickle builder is a subclass of it. + (``pickle``, ``simplejson``, ``phpserialize``, and others) to dump the + generated HTML documentation. The pickle builder is a subclass of it. A concrete subclass of this builder serializing to the `PHP serialization`_ format could look like this:: @@ -319,10 +372,10 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. attribute:: implementation - A module that implements `dump()`, `load()`, `dumps()` and `loads()` + A module that implements ``dump()``, ``load()``, ``dumps()`` and ``loads()`` functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are - `simplejson`, `phpserialize`, `plistlib`, and others. + ``simplejson``, ``phpserialize``, ``plistlib``, and others. .. attribute:: out_suffix @@ -400,9 +453,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. class:: ChangesBuilder This builder produces an HTML overview of all :rst:dir:`versionadded`, - :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the - current :confval:`version`. This is useful to generate a ChangeLog file, for - example. + :rst:dir:`versionchanged`, :rst:dir:`deprecated` and :rst:dir:`versionremoved` + directives for the current :confval:`version`. This is useful to generate a + changelog file, for example. .. autoattribute:: name |