Expand documentation for -M flag.

doc/man/sphinx-build.rst

@@ -4,14 +4,18 @@ sphinx-build
 Synopsis
 --------
 
-**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
+| **sphinx-build** -M <*builder*> <*sourcedir*> <*outputdir*> [*options*]
+| **sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
 
 Description
 -----------
 
 :program:`sphinx-build` generates documentation from the files in
 ``<sourcedir>`` and places it in the ``<outputdir>``.
 
+Please note that there are 2 signatures for 2 usage scenarios. ``-M`` flag
+invokes a :ref:`make mode <make_mode>`, otherwise it works in a *build mode*.
+
 :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,14 @@ the documentation as HTML for the first time.  To do that, run this command:
 
    (.venv) $ sphinx-build -M html docs/source/ docs/build/
 
+.. note::
+
+  Please note that ``-M`` flag is a *make-mode* flag. ``sphinx-build`` also has
+  a *build-mode* that provides more control over cache directories but has less
+  builders available and has a different signature. It is invoked by using a
+  ``-b`` flag. These flags are mutually exclusive. You can find out more in
+  :doc:`sphinx-build's manual </man/sphinx-build>`.
+
 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,47 @@ 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 print_help(self, file: IO[str] | None = None) -> None:
+        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)
+            break
+        return super().print_help(file)
+
+
 def get_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        usage='%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]',
+    parser = ArgParser(
+        usage=('%(prog)s -M BUILDER SOURCEDIR OUTPUTDIR [OPTIONS]\n       '
+               '%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]'),
+        formatter_class=ParagraphFormatter,
         epilog=__('For more information, visit <https://www.sphinx-doc.org/>.'),
         description=__("""
 Generate documentation from source files.
@@ -123,6 +162,13 @@ def get_parser() -> argparse.ArgumentParser:
 settings. The 'sphinx-quickstart' tool may be used to generate template files,
 including 'conf.py'
 
+PLEASE NOTE that there are 2 signatures for 2 usage scenarios. -M flag is a
+special flag that must always come first if used! If present, it alters the
+way the tool works. It can be thought of as a "one-click" solution. It allows
+to build several formats of docs into the same OUTPUTDIR without mixing them
+up (it creates a dedicated directory for each builder). If more control over
+paths is needed then -b flag is the way to go.
+
 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,14 @@ def build_clean(self) -> int:
         return 0
 
     def build_help(self) -> None:
-        if not color_terminal():
+        if not color_terminal() or '--no-color' in sys.argv or '-N' in sys.argv:
             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: