Improve make-mode documentation (#11692)

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,
+   Select a builder, using the *make-mode*.
-   which provides the same build functionality as a default :ref:`Makefile or
+   See :doc:`/usage/builders/index` for a list of all of Sphinx's built-in builders.
-   Make.bat <makefile_options>`. In addition to all Sphinx
+   Extensions can add their own builders.
-   :doc:`/usage/builders/index`, the following build pipelines are available:
 
-   **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::
+   .. note::
-      Sphinx only recognizes the ``-M`` option if it is placed first.
+
+      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

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:

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

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

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.
 

doc/usage/extensions/graphviz.rst

@@ -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
 

doc/usage/extensions/math.rst

@@ -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.

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 <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