From b935915c579573e3812cef1bfb6059b0baeccac6 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Thu, 21 Sep 2023 09:39:39 +0100 Subject: [PATCH] Improve make-mode documentation (#11692) --- doc/man/sphinx-build.rst | 94 +++++++++---------------------- doc/tutorial/getting-started.rst | 2 +- doc/usage/advanced/intl.rst | 2 +- doc/usage/builders/index.rst | 55 +++++++++++++++++- doc/usage/extensions/coverage.rst | 2 +- doc/usage/extensions/graphviz.rst | 2 +- doc/usage/extensions/math.rst | 2 +- doc/usage/quickstart.rst | 6 +- 8 files changed, 89 insertions(+), 76 deletions(-) diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index a1fb9be4024..908017e1964 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -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 `. 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 `, + 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 ``/doctrees`` + * output files are saved to ``/`` .. 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 diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst index 5cf0b38aaa8..678f08db3e7 100644 --- a/doc/tutorial/getting-started.rst +++ b/doc/tutorial/getting-started.rst @@ -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: diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst index ae6e7dc9d6b..e858c3c3207 100644 --- a/doc/usage/advanced/intl.rst +++ b/doc/usage/advanced/intl.rst @@ -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 diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index ce2c5dce08d..92c88839ddc 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 `. -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 diff --git a/doc/usage/extensions/coverage.rst b/doc/usage/extensions/coverage.rst index 1390ebf1155..49a2334a19e 100644 --- a/doc/usage/extensions/coverage.rst +++ b/doc/usage/extensions/coverage.rst @@ -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. diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index c134f6ddb15..231bd369997 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -211,7 +211,7 @@ There are also these config values: :program:`sphinx-build` command line via the :option:`-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 diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst index df4fc6b845c..a6f7449b94e 100644 --- a/doc/usage/extensions/math.rst +++ b/doc/usage/extensions/math.rst @@ -75,7 +75,7 @@ are built: :program:`sphinx-build` command line via the :option:`-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. diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 0773f6030cb..da00bb792b6 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -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 ` option selects a builder; in this example +The :option:`-M ` option selects a builder; in this example Sphinx will build HTML files. |more| Refer to the :doc:`sphinx-build man page ` for all