Expand documentation for -M flag.

doc/man/sphinx-build.rst

@@ -4,14 +4,20 @@ sphinx-build
 Synopsis
 --------
 
-**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
+| **sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
+| **sphinx-build** -M <*builder*> <*sourcedir*> <*outputdir*> [*options*]
 
 Description
 -----------
 
 :program:`sphinx-build` generates documentation from the files in
 ``<sourcedir>`` and places it in the ``<outputdir>``.
 
+The available modes are the *build-mode* via :option:`sphinx-build -b` and the
+*make-mode* via :option:`sphinx-build -M`. Note that these modes have a
+different signature. The *make-mode* always requires the ``-M`` argument to
+come first and options to come last.
+
 :program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
 settings.  :manpage:`sphinx-quickstart(1)` may be used to generate template
 files, including ``conf.py``.

doc/tutorial/getting-started.rst

@@ -106,6 +106,13 @@ the documentation as HTML for the first time.  To do that, run this command:
 
    (.venv) $ sphinx-build -M html docs/source/ docs/build/
 
+.. note::
+
+  :option:`sphinx-build -M` uses the *make-mode* but :program:`sphinx-build`
+  also supports a *build-mode* via :option:`sphinx-build -b` to provide a finer
+  control over the generated artifacts. See the :ref:`sphinx-build's manual
+  </man/sphinx-build>` for details.
+
 And finally, open ``docs/build/html/index.html`` in your browser.  You should see
 something like this:
 

sphinx/cmd/build.py

@@ -9,10 +9,11 @@
 import multiprocessing
 import os
 import pdb  # NoQA: T100
+import re
 import sys
 import traceback
 from os import path
-from typing import TYPE_CHECKING, Any, TextIO
+from typing import IO, TYPE_CHECKING, Any, TextIO
 
 from docutils.utils import SystemMessage
 
@@ -111,9 +112,55 @@ def jobs_argument(value: str) -> int:
             return jobs
 
 
+class ParagraphFormatter(argparse.HelpFormatter):
+    """Wraps help text as a default formatter but keeps paragraps separated."""
+
+    _paragraph_matcher = re.compile(r"\n\n+")
+
+    def _fill_text(self, text: str, width: int, indent: str) -> str:
+        import textwrap
+        result: list[str] = []
+        for p in self._paragraph_matcher.split(text):
+            p = self._whitespace_matcher.sub(' ', p).strip()
+            p = textwrap.fill(p, width,
+                              initial_indent=indent,
+                              subsequent_indent=indent)
+            result.append(p)
+        return '\n\n'.join(result)
+
+
+class ArgParser(argparse.ArgumentParser):
+    """Wraps standard ArgumentParser to add sphinx-specefic flags to help."""
+
+    def __inject_help_entry(self) -> argparse._ArgumentGroup:
+        from gettext import gettext as _
+        # we inject -M flag action to positionals before printing help
+        # so that there is no risk of side effects on actual execution
+        for action_group in self._action_groups:
+            if action_group.title != _('positional arguments'):
+                continue
+            m_flag = argparse.Action(
+                ["-M"], "BUILDER",  # ugly but works
+                help=__('please refer to usage and main help section')
+            )
+            action_group._group_actions.insert(0, m_flag)
+            return action_group
+        err = (
+            "Couldn't find the argument group 'positional arguments' to inject "
+            "-M flag's help info into.")
+        raise TypeError(err)
+
+    def print_help(self, file: IO[str] | None = None) -> None:
+        action_group = self.__inject_help_entry()
+        super().print_help(file)
+        del action_group._group_actions[0]
+
+
 def get_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        usage='%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]',
+    parser = ArgParser(
+        usage=('%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]\n       '
+               '%(prog)s -M BUILDER SOURCEDIR OUTPUTDIR [OPTIONS]'),
+        formatter_class=ParagraphFormatter,
         epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
         description=__("""
 Generate documentation from source files.
@@ -123,6 +170,11 @@ def get_parser() -> argparse.ArgumentParser:
 settings. The 'sphinx-quickstart' tool may be used to generate template files,
 including 'conf.py'
 
+Use the '-M' option to simultaneously build several formats into the same
+OUTPUTDIR. When specified, this option MUST be the first command-line argument.
+If a finer control over the output is needed, use the '-b/--builder' option
+instead. Note that these modes have a different signature.
+
 sphinx-build can create documentation in different formats. A 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

sphinx/cmd/make_mode.py

@@ -17,7 +17,7 @@
 
 import sphinx
 from sphinx.cmd.build import build_main
-from sphinx.util.console import blue, bold, color_terminal, nocolor
+from sphinx.util.console import bold, color_terminal, nocolor, yellow
 from sphinx.util.osutil import rmtree
 
 if sys.version_info >= (3, 11):
@@ -86,14 +86,15 @@ def build_clean(self) -> int:
         return 0
 
     def build_help(self) -> None:
-        if not color_terminal():
+        print(self.opts)
+        if not color_terminal() or '--no-color' in self.opts or '-N' in self.opts:
             nocolor()
 
         print(bold("Sphinx v%s" % sphinx.__display_version__))
-        print("Please use `make %s' where %s is one of" % ((blue('target'),) * 2))
+        print("Please use `make %s' where %s is one of" % ((yellow('target'),) * 2))
         for osname, bname, description in BUILDERS:
             if not osname or os.name == osname:
-                print(f'  {blue(bname.ljust(10))}  {description}')
+                print(f'  {yellow(bname.ljust(10))}  {description}')
 
     def build_latexpdf(self) -> int:
         if self.run_generic_build('latex') > 0: