diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 0d49ea469b5..74a546b9175 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -14,7 +14,7 @@ Description ```` and places it in the ````. Please note that there are 2 signatures for 2 usage scenarios. ``-M`` flag -invokes a :ref:`make mode `, otherwise it works in a `build mode`. +invokes a :ref:`make mode `, otherwise it works in a *build mode*. :program:`sphinx-build` looks for ``/conf.py`` for the configuration settings. :manpage:`sphinx-quickstart(1)` may be used to generate template diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst index f8e5188218e..3b0821eea16 100644 --- a/doc/tutorial/getting-started.rst +++ b/doc/tutorial/getting-started.rst @@ -108,8 +108,8 @@ the documentation as HTML for the first time. To do that, run this command: .. 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 + 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 `. diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py index e8041b7440f..74e99b1229a 100644 --- a/sphinx/cmd/build.py +++ b/sphinx/cmd/build.py @@ -13,7 +13,7 @@ import sys import traceback from os import path -from typing import TYPE_CHECKING, Any, TextIO, IO +from typing import IO, TYPE_CHECKING, Any, TextIO from docutils.utils import SystemMessage @@ -111,8 +111,10 @@ def jobs_argument(value: str) -> int: else: 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: @@ -126,25 +128,30 @@ def _fill_text(self, text: str, width: int, indent: str) -> str: 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 not action_group.title == _('positional arguments'): + 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')) + 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 = ArgParser( - usage=( '%(prog)s -M BUILDER SOURCEDIR OUTPUTDIR [OPTIONS]\n' - ' %(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]'), + usage=('%(prog)s -M BUILDER SOURCEDIR OUTPUTDIR [OPTIONS]\n ' + '%(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]'), formatter_class=ParagraphFormatter, epilog=__('For more information, visit .'), description=__(""" diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py index 1423a213bf9..43cc67371a7 100644 --- a/sphinx/cmd/make_mode.py +++ b/sphinx/cmd/make_mode.py @@ -17,7 +17,7 @@ import sphinx from sphinx.cmd.build import build_main -from sphinx.util.console import yellow, 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):