mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Improve make-mode documentation (#11692)
This commit is contained in:
Adam Turner
GitHub
parent
de6d3665ef
commit
b935915c57
@ -20,7 +20,7 @@ files, including ``conf.py``.
|
||||
format is selected by specifying the builder name on the command line; it
|
||||
defaults to HTML. Builders can also perform other tasks related to
|
||||
documentation processing. For a list of available builders, refer to
|
||||
:option:`sphinx-build -b`.
|
||||
:doc:`/usage/builders/index`.
|
||||
|
||||
By default, everything that is outdated is built. Output only for selected
|
||||
files can be built by specifying individual filenames.
|
||||
@ -30,87 +30,47 @@ Options
|
||||
|
||||
.. program:: sphinx-build
|
||||
|
||||
.. option:: -b buildername
|
||||
|
||||
The most important option: it selects 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.
|
||||
|
||||
See :doc:`/usage/builders/index` for a list of all builders shipped with
|
||||
Sphinx. Extensions can add their own builders.
|
||||
|
||||
.. _make_mode:
|
||||
|
||||
.. option:: -M buildername
|
||||
|
||||
Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module,
|
||||
which provides the same build functionality as a default :ref:`Makefile or
|
||||
Make.bat <makefile_options>`. In addition to all Sphinx
|
||||
:doc:`/usage/builders/index`, the following build pipelines are available:
|
||||
Select a builder, using the *make-mode*.
|
||||
See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders.
|
||||
Extensions can add their own builders.
|
||||
|
||||
**latexpdf**
|
||||
.. important::
|
||||
Sphinx only recognizes the ``-M`` option if it is used first.
|
||||
|
||||
The *make-mode* provides the same build functionality as
|
||||
a default :ref:`Makefile or Make.bat <makefile_options>`,
|
||||
and provides the following additional build pipelines:
|
||||
|
||||
*latexpdf*
|
||||
Build LaTeX files and run them through :program:`pdflatex`, or as per
|
||||
:confval:`latex_engine` setting.
|
||||
If :confval:`language` is set to ``'ja'``, will use automatically
|
||||
the :program:`platex/dvipdfmx` latex to PDF pipeline.
|
||||
|
||||
**info**
|
||||
*info*
|
||||
Build Texinfo files and run them through :program:`makeinfo`.
|
||||
|
||||
.. important::
|
||||
Sphinx only recognizes the ``-M`` option if it is placed first.
|
||||
.. note::
|
||||
|
||||
The default output directory locations when using *make-mode*
|
||||
differ from the defaults when using :option:`-b`.
|
||||
|
||||
* doctrees are saved to ``<outputdir>/doctrees``
|
||||
* output files are saved to ``<outputdir>/<builder name>``
|
||||
|
||||
.. versionadded:: 1.2.1
|
||||
|
||||
.. option:: -b buildername
|
||||
|
||||
Selects a builder.
|
||||
|
||||
See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders.
|
||||
Extensions can add their own builders.
|
||||
|
||||
.. option:: -a
|
||||
|
||||
If given, always write all output files. The default is to only write output
|
||||
|
||||
@ -104,7 +104,7 @@ the documentation as HTML for the first time. To do that, run this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
(.venv) $ sphinx-build -b html docs/source/ docs/build/html
|
||||
(.venv) $ sphinx-build -M html docs/source/ docs/build/
|
||||
|
||||
And finally, open ``docs/build/html/index.html`` in your browser. You should see
|
||||
something like this:
|
||||
|
||||
@ -27,7 +27,7 @@ Sphinx uses these facilities to translate whole documents.
|
||||
|
||||
Initially project maintainers have to collect all translatable strings (also
|
||||
referred to as *messages*) to make them known to translators. Sphinx extracts
|
||||
these through invocation of ``sphinx-build -b gettext``.
|
||||
these through invocation of ``sphinx-build -M gettext``.
|
||||
|
||||
Every single element in the doctree will end up in a single message which
|
||||
results in lists being equally split into different chunks while large
|
||||
|
||||
@ -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
|
||||
|
||||
@ -9,7 +9,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
|
||||
.. class:: CoverageBuilder
|
||||
|
||||
To use this builder, activate the coverage extension in your configuration
|
||||
file and give ``-b coverage`` on the command line.
|
||||
file and give ``-M coverage`` on the command line.
|
||||
|
||||
.. todo:: Write this section.
|
||||
|
||||
|
||||
@ -211,7 +211,7 @@ There are also these config values:
|
||||
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
|
||||
option should be preferable, like this::
|
||||
|
||||
sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
|
||||
sphinx-build -M html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build
|
||||
|
||||
.. confval:: graphviz_dot_args
|
||||
|
||||
|
||||
@ -75,7 +75,7 @@ are built:
|
||||
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
|
||||
option should be preferable, like this::
|
||||
|
||||
sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
|
||||
sphinx-build -M html -D imgmath_latex=C:\tex\latex.exe . _build
|
||||
|
||||
This value should only contain the path to the latex executable, not further
|
||||
arguments; use :confval:`imgmath_latex_args` for that purpose.
|
||||
|
||||
@ -130,11 +130,11 @@ docs. A build is started with the :program:`sphinx-build` program:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-build -b html sourcedir builddir
|
||||
$ sphinx-build -M html sourcedir outputdir
|
||||
|
||||
where *sourcedir* is the :term:`source directory`, and *builddir* is the
|
||||
where *sourcedir* is the :term:`source directory`, and *outputdir* is the
|
||||
directory in which you want to place the built documentation.
|
||||
The :option:`-b <sphinx-build -b>` option selects a builder; in this example
|
||||
The :option:`-M <sphinx-build -M>` option selects a builder; in this example
|
||||
Sphinx will build HTML files.
|
||||
|
||||
|more| Refer to the :doc:`sphinx-build man page </man/sphinx-build>` for all
|
||||
|
||||
Loading…
Reference in New Issue
Block a user