Sphinx 8.0.2__py3-none-any.whl → 8.1.1__py3-none-any.whl

sphinx/__init__.py

@@ -1,6 +1,6 @@
 """The Sphinx documentation toolchain."""
 
-__version__ = '8.0.2'
+__version__ = '8.1.1'
 __display_version__ = __version__  # used for command line version
 
 # Keep this file executable as-is in Python 3!
@@ -16,7 +16,10 @@ if 'PYTHONWARNINGS' not in os.environ:
 
     warnings.filterwarnings('default', category=RemovedInNextVersionWarning)
 warnings.filterwarnings(
-    'ignore', 'The frontend.Option class .*', DeprecationWarning, module='docutils.frontend'
+    'ignore',
+    'The frontend.Option class .*',
+    DeprecationWarning,
+    module='docutils.frontend',
 )
 
 #: Version info for better programmatic use.
@@ -27,7 +30,7 @@ warnings.filterwarnings(
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 0, 2, 'final', 0)
+version_info = (8, 1, 1, 'final', 0)
 
 package_dir = os.path.abspath(os.path.dirname(__file__))
 

sphinx/_cli/__init__.py

@@ -38,7 +38,9 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Sequence
     from typing import NoReturn, TypeAlias
 
-    _PARSER_SETUP: TypeAlias = Callable[[argparse.ArgumentParser], argparse.ArgumentParser]
+    _PARSER_SETUP: TypeAlias = Callable[
+        [argparse.ArgumentParser], argparse.ArgumentParser
+    ]
     _RUNNER: TypeAlias = Callable[[argparse.Namespace], int]
 
     from typing import Protocol
@@ -50,8 +52,7 @@ if TYPE_CHECKING:
 
 
 # Map of command name to import path.
-_COMMANDS: dict[str, str] = {
-}
+_COMMANDS: dict[str, str] = {}
 
 
 def _load_subcommand_descriptions() -> Iterator[tuple[str, str]]:
@@ -61,7 +62,7 @@ def _load_subcommand_descriptions() -> Iterator[tuple[str, str]]:
             description = module.parser_description
         except AttributeError:
             # log an error here, but don't fail the full enumeration
-            print(f"Failed to load the description for {command}", file=sys.stderr)
+            print(f'Failed to load the description for {command}', file=sys.stderr)
         else:
             yield command, description.split('\n\n', 1)[0]
 
@@ -79,7 +80,8 @@ class _RootArgumentParser(argparse.ArgumentParser):
         ]
 
         if commands := list(_load_subcommand_descriptions()):
-            command_max_length = min(max(map(len, next(zip(*commands, strict=True), ()))), 22)
+            command_lengths = map(len, next(zip(*commands, strict=True), ()))
+            command_max_length = min(max(command_lengths), 22)
             help_fragments += [
                 '\n',
                 bold(underline(__('Commands:'))),
@@ -95,8 +97,11 @@ class _RootArgumentParser(argparse.ArgumentParser):
         # Uppercase the title of the Optionals group
         self._optionals.title = __('Options')
         for argument_group in self._action_groups[1:]:
-            if arguments := [action for action in argument_group._group_actions
-                             if action.help != argparse.SUPPRESS]:
+            if arguments := [
+                action
+                for action in argument_group._group_actions
+                if action.help != argparse.SUPPRESS
+            ]:
                 help_fragments += self._format_optional_arguments(
                     arguments,
                     argument_group.title or '',
@@ -104,7 +109,9 @@ class _RootArgumentParser(argparse.ArgumentParser):
 
         help_fragments += [
             '\n',
-            __('For more information, visit https://www.sphinx-doc.org/en/master/man/.'),
+            __(
+                'For more information, visit https://www.sphinx-doc.org/en/master/man/.'
+            ),
             '\n',
         ]
         return ''.join(help_fragments)
@@ -123,7 +130,7 @@ class _RootArgumentParser(argparse.ArgumentParser):
             opt = prefix + '  ' + ', '.join(map(bold, action.option_strings))
             if action.nargs != 0:
                 opt += ' ' + self._format_metavar(
-                    action.nargs, action.metavar, action.choices, action.dest,
+                    action.nargs, action.metavar, action.choices, action.dest
                 )
             yield opt
             yield '\n'
@@ -161,10 +168,11 @@ class _RootArgumentParser(argparse.ArgumentParser):
         raise ValueError(msg)
 
     def error(self, message: str) -> NoReturn:
-        sys.stderr.write(__(
-            '{0}: error: {1}\n'
-            "Run '{0} --help' for information"  # NoQA: COM812
-        ).format(self.prog, message))
+        sys.stderr.write(
+            __(
+                '{0}: error: {1}\n' "Run '{0} --help' for information"  # NoQA: COM812
+            ).format(self.prog, message)
+        )
         raise SystemExit(2)
 
 
@@ -172,18 +180,23 @@ def _create_parser() -> _RootArgumentParser:
     parser = _RootArgumentParser(
         prog='sphinx',
         description=__('   Manage documentation with Sphinx.'),
-        epilog=__('For more information, visit https://www.sphinx-doc.org/en/master/man/.'),
+        epilog=__(
+            'For more information, visit https://www.sphinx-doc.org/en/master/man/.'
+        ),
         add_help=False,
         allow_abbrev=False,
     )
     parser.add_argument(
-        '-V', '--version',
+        '-V',
+        '--version',
         action='store_true',
         default=argparse.SUPPRESS,
         help=__('Show the version and exit.'),
     )
     parser.add_argument(
-        '-h', '-?', '--help',
+        '-h',
+        '-?',
+        '--help',
         action='store_true',
         default=argparse.SUPPRESS,
         help=__('Show this message and exit.'),
@@ -192,14 +205,16 @@ def _create_parser() -> _RootArgumentParser:
     # logging control
     log_control = parser.add_argument_group(__('Logging'))
     log_control.add_argument(
-        '-v', '--verbose',
+        '-v',
+        '--verbose',
         action='count',
         dest='verbosity',
         default=0,
         help=__('Increase verbosity (can be repeated)'),
     )
     log_control.add_argument(
-        '-q', '--quiet',
+        '-q',
+        '--quiet',
         action='store_const',
         dest='verbosity',
         const=-1,
@@ -235,6 +250,7 @@ def _parse_command(argv: Sequence[str] = ()) -> tuple[str, Sequence[str]]:
     # Handle '--version' or '-V' passed to the main command or any subcommand
     if 'version' in args or {'-V', '--version'}.intersection(command_argv):
         from sphinx import __display_version__
+
         sys.stderr.write(f'sphinx {__display_version__}\n')
         raise SystemExit(0)
 
@@ -245,8 +261,12 @@ def _parse_command(argv: Sequence[str] = ()) -> tuple[str, Sequence[str]]:
         raise SystemExit(0)
 
     if command_name not in _COMMANDS:
-        sys.stderr.write(__(f'sphinx: {command_name!r} is not a sphinx command. '
-                            "See 'sphinx --help'.\n"))
+        sys.stderr.write(
+            __(
+                f'sphinx: {command_name!r} is not a sphinx command. '
+                "See 'sphinx --help'.\n"
+            )
+        )
         raise SystemExit(2)
 
     return command_name, command_argv

sphinx/_cli/util/colour.py

@@ -17,6 +17,8 @@ def terminal_supports_colour() -> bool:
     """Return True if coloured terminal output is supported."""
     if 'NO_COLOUR' in os.environ or 'NO_COLOR' in os.environ:
         return False
+    if sys.platform == 'win32':
+        colorama.just_fix_windows_console()
     if 'FORCE_COLOUR' in os.environ or 'FORCE_COLOR' in os.environ:
         return True
 
@@ -35,15 +37,11 @@ def terminal_supports_colour() -> bool:
 def disable_colour() -> None:
     global _COLOURING_DISABLED
     _COLOURING_DISABLED = True
-    if sys.platform == 'win32':
-        colorama.deinit()
 
 
 def enable_colour() -> None:
     global _COLOURING_DISABLED
     _COLOURING_DISABLED = False
-    if sys.platform == 'win32':
-        colorama.init()
 
 
 def colourise(colour_name: str, text: str, /) -> str:
@@ -57,6 +55,7 @@ def _create_colour_func(escape_code: str, /) -> Callable[[str], str]:
         if _COLOURING_DISABLED:
             return text
         return f'\x1b[{escape_code}m{text}\x1b[39;49;00m'
+
     return inner
 
 
@@ -69,11 +68,13 @@ def _create_colour_func(escape_code: str, /) -> Callable[[str], str]:
 if sys.platform == 'win32':
     _create_input_mode_colour_func = _create_colour_func
 else:
+
     def _create_input_mode_colour_func(escape_code: str, /) -> Callable[[str], str]:
         def inner(text: str) -> str:
             if _COLOURING_DISABLED:
                 return text
             return f'\x01\x1b[{escape_code}m\x02{text}\x01\x1b[39;49;00m\x02'
+
         return inner
 
 

sphinx/_cli/util/errors.py

@@ -72,10 +72,15 @@ def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
     if app is not None:
         extensions = app.extensions.values()
         last_msgs = '\n'.join(f'* {strip_colors(s)}' for s in app.messagelog)
-        exts_list = '\n'.join(f'* {ext.name} ({ext.version})' for ext in extensions
-                              if ext.version != 'builtin')
-
-    with tempfile.NamedTemporaryFile(suffix='.log', prefix='sphinx-err-', delete=False) as f:
+        exts_list = '\n'.join(
+            f'* {ext.name} ({ext.version})'
+            for ext in extensions
+            if ext.version != 'builtin'
+        )
+
+    with tempfile.NamedTemporaryFile(
+        suffix='.log', prefix='sphinx-err-', delete=False
+    ) as f:
         f.write(error_info(last_msgs, exts_list, exc_format).encode('utf-8'))
 
     return f.name
@@ -143,9 +148,13 @@ def handle_exception(
         print_red(__('Recursion error:'))
         print_err(str(exception))
         print_err()
-        print_err(__('This can happen with very large or deeply nested source '
-                     'files. You can carefully increase the default Python '
-                     'recursion limit of 1000 in conf.py with e.g.:'))
+        print_err(
+            __(
+                'This can happen with very large or deeply nested source '
+                'files. You can carefully increase the default Python '
+                'recursion limit of 1000 in conf.py with e.g.:'
+            )
+        )
         print_err('\n    import sys\n    sys.setrecursionlimit(1_500)\n')
         return
 
@@ -159,7 +168,15 @@ def handle_exception(
     print_err(__('The full traceback has been saved in:'))
     print_err(traceback_info_path)
     print_err()
-    print_err(__('To report this error to the developers, please open an issue '
-                 'at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!'))
-    print_err(__('Please also report this if it was a user error, so '
-                 'that a better error message can be provided next time.'))
+    print_err(
+        __(
+            'To report this error to the developers, please open an issue '
+            'at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!'
+        )
+    )
+    print_err(
+        __(
+            'Please also report this if it was a user error, so '
+            'that a better error message can be provided next time.'
+        )
+    )