Sphinx 8.1.3__py3-none-any.whl → 8.2.0rc1__py3-none-any.whl

sphinx/__init__.py

@@ -1,6 +1,8 @@
 """The Sphinx documentation toolchain."""
 
-__version__ = '8.1.3'
+from __future__ import annotations
+
+__version__ = '8.2.0rc1'
 __display_version__ = __version__  # used for command line version
 
 # Keep this file executable as-is in Python 3!
@@ -9,6 +11,8 @@ __display_version__ = __version__  # used for command line version
 import os
 import warnings
 
+from sphinx.util._pathlib import _StrPath
+
 # by default, all DeprecationWarning under sphinx package will be emit.
 # Users can avoid this by using environment variable: PYTHONWARNINGS=
 if 'PYTHONWARNINGS' not in os.environ:
@@ -30,9 +34,9 @@ warnings.filterwarnings(
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 1, 3, 'final', 0)
+version_info = (8, 2, 0, 'candidate', 1)
 
-package_dir = os.path.abspath(os.path.dirname(__file__))
+package_dir = _StrPath(__file__).resolve().parent
 
 _in_development = False
 if _in_development:
@@ -41,7 +45,7 @@ if _in_development:
 
     try:
         if ret := subprocess.run(
-            ['git', 'rev-parse', '--short', 'HEAD'],
+            ['git', 'rev-parse', '--short', 'HEAD'],  # NoQA: S607
             cwd=package_dir,
             capture_output=True,
             check=False,

sphinx/__main__.py

@@ -1,5 +1,7 @@
 """The Sphinx documentation toolchain."""
 
+from __future__ import annotations
+
 import sys
 
 from sphinx.cmd.build import main

sphinx/_cli/__init__.py

@@ -168,11 +168,8 @@ 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)
-        )
+        msg = __("{0}: error: {1}\nRun '{0} --help' for information")
+        sys.stderr.write(msg.format(self.prog, message))
         raise SystemExit(2)
 
 

sphinx/_cli/util/colour.py

@@ -2,24 +2,32 @@
 
 from __future__ import annotations
 
-import os
 import sys
-from collections.abc import Callable  # NoQA: TCH003
+from os import environ as _environ
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Callable
 
 if sys.platform == 'win32':
     import colorama
 
+    colorama.just_fix_windows_console()
+    del colorama
+
 
-_COLOURING_DISABLED = True
+_COLOURING_DISABLED = False
 
 
 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:
+    if 'NO_COLOUR' in _environ or 'NO_COLOR' in _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
+    if 'FORCE_COLOUR' in _environ or 'FORCE_COLOR' in _environ:
+        return True
+    if _environ.get('CI', '').lower() in {'true', '1'}:
         return True
 
     try:
@@ -31,23 +39,37 @@ def terminal_supports_colour() -> bool:
         return False
 
     # Do not colour output if on a dumb terminal
-    return os.environ.get('TERM', 'unknown').lower() not in {'dumb', 'unknown'}
+    return _environ.get('TERM', 'unknown').lower() not in {'dumb', 'unknown'}
 
 
 def disable_colour() -> None:
-    global _COLOURING_DISABLED
+    global _COLOURING_DISABLED  # NoQA: PLW0603
     _COLOURING_DISABLED = True
 
 
 def enable_colour() -> None:
-    global _COLOURING_DISABLED
+    global _COLOURING_DISABLED  # NoQA: PLW0603
     _COLOURING_DISABLED = False
 
 
 def colourise(colour_name: str, text: str, /) -> str:
     if _COLOURING_DISABLED:
         return text
-    return globals()[colour_name](text)
+    if colour_name.startswith('_') or colour_name in {
+        'annotations',
+        'sys',
+        'terminal_supports_colour',
+        'disable_colour',
+        'enable_colour',
+        'colourise',
+    }:
+        msg = f'Invalid colour name: {colour_name!r}'
+        raise ValueError(msg)
+    try:
+        return globals()[colour_name](text)
+    except KeyError:
+        msg = f'Invalid colour name: {colour_name!r}'
+        raise ValueError(msg) from None
 
 
 def _create_colour_func(escape_code: str, /) -> Callable[[str], str]:
@@ -56,6 +78,7 @@ def _create_colour_func(escape_code: str, /) -> Callable[[str], str]:
             return text
         return f'\x1b[{escape_code}m{text}\x1b[39;49;00m'
 
+    inner.__escape_code = escape_code  # type: ignore[attr-defined]
     return inner
 
 
@@ -73,7 +96,7 @@ else:
         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 f'\1\x1b[{escape_code}m\2{text}\1\x1b[39;49;00m\2'
 
         return inner
 

sphinx/_cli/util/errors.py

@@ -2,15 +2,35 @@ from __future__ import annotations
 
 import re
 import sys
-import tempfile
-from typing import TYPE_CHECKING, TextIO
+from typing import TYPE_CHECKING
 
-from sphinx.errors import SphinxParallelError
+from sphinx.errors import SphinxError, SphinxParallelError
 
 if TYPE_CHECKING:
-    from sphinx.application import Sphinx
+    from collections.abc import Collection
+    from typing import Final, Protocol
 
-_ANSI_COLOUR_CODES: re.Pattern[str] = re.compile('\x1b.*?m')
+    from sphinx.extension import Extension
+
+    class SupportsWrite(Protocol):
+        def write(self, text: str, /) -> int | None: ...
+
+
+_CSI: Final[str] = re.escape('\x1b[')  # 'ESC [': Control Sequence Introducer
+
+# Pattern matching ANSI CSI colors (SGR) and erase line (EL) sequences.
+#
+# See ``_strip_escape_sequences()`` for details.
+_ANSI_CODES: Final[re.Pattern[str]] = re.compile(
+    '\x1b'
+    r"""\[
+    (?:
+      (?:\d+;){0,2}\d*m  # ANSI color code    ('m' is equivalent to '0m')
+    |
+      [012]?K            # ANSI Erase in Line ('K' is equivalent to '0K')
+    )""",
+    re.VERBOSE | re.ASCII,
+)
 
 
 def terminal_safe(s: str, /) -> str:
@@ -18,11 +38,63 @@ def terminal_safe(s: str, /) -> str:
     return s.encode('ascii', 'backslashreplace').decode('ascii')
 
 
-def strip_colors(s: str, /) -> str:
-    return _ANSI_COLOUR_CODES.sub('', s).strip()
+def strip_escape_sequences(text: str, /) -> str:
+    r"""Remove the ANSI CSI colors and "erase in line" sequences.
+
+    Other `escape sequences <https://en.wikipedia.org/wiki/ANSI_escape_code>`_
+    (e.g., VT100-specific functions) are not supported. Only control sequences
+    *natively* known to Sphinx (i.e., colour sequences used in Sphinx
+    and "erase entire line" (``'\x1b[2K'``)) are stripped by this function.
+
+    .. warning:: This function only for use within Sphinx..
+
+    __ https://en.wikipedia.org/wiki/ANSI_escape_code
+    """
+    return _ANSI_CODES.sub('', text)
+
+
+def full_exception_context(
+    exception: BaseException,
+    *,
+    message_log: Collection[str] = (),
+    extensions: Collection[Extension] = (),
+    full_traceback: bool = True,
+) -> str:
+    """Return a formatted message containing useful debugging context."""
+    messages = [f'    {strip_escape_sequences(msg)}'.rstrip() for msg in message_log]
+    while messages and not messages[-1]:
+        messages.pop()
+    last_msgs = '\n'.join(messages)
+    exts_list = '\n'.join(
+        f'* {ext.name} ({ext.version})'
+        for ext in extensions
+        if ext.version != 'builtin'
+    )
+    exc_format = format_traceback(exception, short_traceback=not full_traceback)
+    return error_info(last_msgs or 'None.', exts_list or 'None.', exc_format)
+
+
+def format_traceback(
+    exception: BaseException, /, *, short_traceback: bool = False
+) -> str:
+    """Format the given exception's traceback."""
+    if short_traceback:
+        from traceback import TracebackException
+
+        # format an exception with traceback, but only the last frame.
+        te = TracebackException.from_exception(exception, limit=-1)
+        exc_format = te.stack.format()[-1] + ''.join(te.format_exception_only())
+    elif isinstance(exception, SphinxParallelError):
+        exc_format = f'(Error in parallel process)\n{exception.traceback}'
+    else:
+        from traceback import format_exception
+
+        exc_format = ''.join(format_exception(exception))
+    return '\n'.join(f'    {line}' for line in exc_format.rstrip().splitlines())
 
 
 def error_info(messages: str, extensions: str, traceback: str) -> str:
+    """Format the traceback and extensions list with environment information."""
     import platform
 
     import docutils
@@ -59,29 +131,30 @@ Traceback
 """
 
 
-def save_traceback(app: Sphinx | None, exc: BaseException) -> str:
+def save_traceback(
+    exception: BaseException,
+    *,
+    message_log: Collection[str] = (),
+    extensions: Collection[Extension] = (),
+) -> str:
     """Save the given exception's traceback in a temporary file."""
-    if isinstance(exc, SphinxParallelError):
-        exc_format = '(Error in parallel process)\n' + exc.traceback
-    else:
-        import traceback
-
-        exc_format = traceback.format_exc()
-
-    last_msgs = exts_list = ''
-    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'
-        )
+    output = full_exception_context(
+        exception=exception,
+        message_log=message_log,
+        extensions=extensions,
+    )
+    filename = write_temporary_file(output)
+    return filename
+
+
+def write_temporary_file(content: str) -> str:
+    """Write content to a temporary file and return the filename."""
+    import tempfile
 
     with tempfile.NamedTemporaryFile(
-        suffix='.log', prefix='sphinx-err-', delete=False
+        'w', encoding='utf-8', suffix='.log', prefix='sphinx-err-', delete=False
     ) as f:
-        f.write(error_info(last_msgs, exts_list, exc_format).encode('utf-8'))
+        f.write(content)
 
     return f.name
 
@@ -90,18 +163,17 @@ def handle_exception(
     exception: BaseException,
     /,
     *,
-    stderr: TextIO = sys.stderr,
+    stderr: SupportsWrite = sys.stderr,
     use_pdb: bool = False,
     print_traceback: bool = False,
-    app: Sphinx | None = None,
+    message_log: Collection[str] = (),
+    extensions: Collection[Extension] = (),
 ) -> None:
     from bdb import BdbQuit
-    from traceback import TracebackException, print_exc
 
     from docutils.utils import SystemMessage
 
     from sphinx._cli.util.colour import red
-    from sphinx.errors import SphinxError
     from sphinx.locale import __
 
     if isinstance(exception, BdbQuit):
@@ -114,57 +186,52 @@ def handle_exception(
         print_err(*map(red, values))
 
     print_err()
-    if print_traceback or use_pdb:
-        print_exc(file=stderr)
-        print_err()
-
-    if use_pdb:
-        from pdb import post_mortem
-
-        print_red(__('Exception occurred, starting debugger:'))
-        post_mortem()
-        return
-
-    if isinstance(exception, KeyboardInterrupt):
+    if not use_pdb and isinstance(exception, KeyboardInterrupt):
         print_err(__('Interrupted!'))
         return
 
     if isinstance(exception, SystemMessage):
-        print_red(__('reStructuredText markup error:'))
-        print_err(str(exception))
-        return
+        print_red(__('reStructuredText markup error!'))
 
     if isinstance(exception, SphinxError):
-        print_red(f'{exception.category}:')
-        print_err(str(exception))
-        return
+        print_red(f'{exception.category}!')
 
     if isinstance(exception, UnicodeError):
-        print_red(__('Encoding error:'))
-        print_err(str(exception))
-        return
+        print_red(__('Encoding error!'))
 
     if isinstance(exception, RecursionError):
-        print_red(__('Recursion error:'))
-        print_err(str(exception))
+        print_red(__('Recursion error!'))
         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.:'
+                'recursion limit of 1,000 in conf.py with e.g.:'
             )
         )
         print_err('\n    import sys\n    sys.setrecursionlimit(1_500)\n')
-        return
 
-    # format an exception with traceback, but only the last frame.
-    te = TracebackException.from_exception(exception, limit=-1)
-    formatted_tb = te.stack.format()[-1] + ''.join(te.format_exception_only()).rstrip()
+    print_err()
+    error_context = full_exception_context(
+        exception,
+        message_log=message_log,
+        extensions=extensions,
+        full_traceback=print_traceback or use_pdb,
+    )
+    print_err(error_context)
+    print_err()
+
+    if use_pdb:
+        from pdb import post_mortem
 
-    print_red(__('Exception occurred:'))
-    print_err(formatted_tb)
-    traceback_info_path = save_traceback(app, exception)
+        print_red(__('Starting debugger:'))
+        post_mortem(exception.__traceback__)
+        return
+
+    # Save full traceback to log file
+    traceback_info_path = save_traceback(
+        exception, message_log=message_log, extensions=extensions
+    )
     print_err(__('The full traceback has been saved in:'))
     print_err(traceback_info_path)
     print_err()

sphinx/addnodes.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
+from docutils.nodes import document  # NoQA: F401
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Any
 
     from docutils.nodes import Element
 
@@ -15,21 +17,6 @@ if TYPE_CHECKING:
     from sphinx.util.typing import ExtensionMetadata
 
 
-class document(nodes.document):
-    """The document root element patched by Sphinx.
-
-    This fixes that document.set_id() does not support a node having multiple node Ids.
-    see https://sourceforge.net/p/docutils/patches/167/
-
-    .. important:: This is only for Sphinx internal use.  Please don't use this
-                   in your extensions.  It will be removed without deprecation period.
-    """
-
-    def set_id(self, node: Element, msgnode: Element | None = None,
-               suggested_prefix: str = '') -> str:
-        return super().set_id(node, msgnode, suggested_prefix)
-
-
 class translatable(nodes.Node):
     """Node which supports translation.
 
@@ -48,7 +35,9 @@ class translatable(nodes.Node):
         """Preserve original translatable messages."""
         raise NotImplementedError
 
-    def apply_translated_message(self, original_message: str, translated_message: str) -> None:
+    def apply_translated_message(
+        self, original_message: str, translated_message: str
+    ) -> None:
         """Apply translated message."""
         raise NotImplementedError
 
@@ -80,7 +69,9 @@ class toctree(nodes.General, nodes.Element, translatable):
         if self.get('caption'):
             self['rawcaption'] = self['caption']
 
-    def apply_translated_message(self, original_message: str, translated_message: str) -> None:
+    def apply_translated_message(
+        self, original_message: str, translated_message: str
+    ) -> None:
         # toctree entries
         for i, (title, docname) in enumerate(self['entries']):
             if title == original_message:
@@ -106,6 +97,7 @@ class toctree(nodes.General, nodes.Element, translatable):
 # Domain-specific object descriptions (class, function etc.)
 #############################################################
 
+
 class _desc_classes_injector(nodes.Element, not_smartquotable):
     """Helper base class for injecting a fixed list of classes.
 
@@ -122,6 +114,7 @@ class _desc_classes_injector(nodes.Element, not_smartquotable):
 # Top-level nodes
 #################
 
+
 class desc(nodes.Admonition, nodes.Element):
     """Node for a list of object signatures and a common description of them.
 
@@ -138,7 +131,9 @@ class desc(nodes.Admonition, nodes.Element):
     #  that forces the specification of the domain and objtyp?
 
 
-class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.TextElement):
+class desc_signature(
+    _desc_classes_injector, nodes.Part, nodes.Inline, nodes.TextElement
+):
     """Node for a single object signature.
 
     As default the signature is a single-line signature.
@@ -198,7 +193,10 @@ class desc_inline(_desc_classes_injector, nodes.Inline, nodes.TextElement):
 
 # nodes to use within a desc_signature or desc_signature_line
 
-class desc_name(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTextElement):
+
+class desc_name(
+    _desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTextElement
+):
     """Node for the main object name.
 
     For example, in the declaration of a Python class ``MyModule.MyClass``,
@@ -210,7 +208,9 @@ class desc_name(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTex
     classes = ['sig-name', 'descname']  # 'descname' is for backwards compatibility
 
 
-class desc_addname(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTextElement):
+class desc_addname(
+    _desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTextElement
+):
     """Node for additional name parts for an object.
 
     For example, in the declaration of a Python class ``MyModule.MyClass``,
@@ -244,6 +244,8 @@ class desc_parameterlist(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     As default the parameter list is written in line with the rest of the signature.
     Set ``multi_line_parameter_list = True`` to describe a multi-line parameter list.
     In that case each parameter will then be written on its own, indented line.
+    A trailing comma will be added on the last line
+    if ``multi_line_trailing_comma`` is True.
     """
 
     child_text_separator = ', '
@@ -258,6 +260,8 @@ class desc_type_parameter_list(nodes.Part, nodes.Inline, nodes.FixedTextElement)
     As default the type parameters list is written in line with the rest of the signature.
     Set ``multi_line_parameter_list = True`` to describe a multi-line type parameters list.
     In that case each type parameter will then be written on its own, indented line.
+    A trailing comma will be added on the last line
+    if ``multi_line_trailing_comma`` is True.
     """
 
     child_text_separator = ', '
@@ -305,13 +309,15 @@ SIG_ELEMENTS: set[type[desc_sig_element]] = set()
 # When adding a new one, add it to SIG_ELEMENTS via the class
 # keyword argument `_sig_element=True` (e.g., see `desc_sig_space`).
 
+
 class desc_sig_element(nodes.inline, _desc_classes_injector):
     """Common parent class of nodes for inline text of a signature."""
 
     classes: list[str] = []
 
-    def __init__(self, rawsource: str = '', text: str = '',
-                 *children: Element, **attributes: Any) -> None:
+    def __init__(
+        self, rawsource: str = '', text: str = '', *children: Element, **attributes: Any
+    ) -> None:
         super().__init__(rawsource, text, *children, **attributes)
         self['classes'].extend(self.classes)
 
@@ -325,67 +331,74 @@ class desc_sig_element(nodes.inline, _desc_classes_injector):
 # to not reinvent the wheel, the classes in the following desc_sig classes
 # are based on those used in Pygments
 
+
 class desc_sig_space(desc_sig_element, _sig_element=True):
     """Node for a space in a signature."""
 
-    classes = ["w"]
+    classes = ['w']
 
-    def __init__(self, rawsource: str = '', text: str = ' ',
-                 *children: Element, **attributes: Any) -> None:
+    def __init__(
+        self,
+        rawsource: str = '',
+        text: str = ' ',
+        *children: Element,
+        **attributes: Any,
+    ) -> None:
         super().__init__(rawsource, text, *children, **attributes)
 
 
 class desc_sig_name(desc_sig_element, _sig_element=True):
     """Node for an identifier in a signature."""
 
-    classes = ["n"]
+    classes = ['n']
 
 
 class desc_sig_operator(desc_sig_element, _sig_element=True):
     """Node for an operator in a signature."""
 
-    classes = ["o"]
+    classes = ['o']
 
 
 class desc_sig_punctuation(desc_sig_element, _sig_element=True):
     """Node for punctuation in a signature."""
 
-    classes = ["p"]
+    classes = ['p']
 
 
 class desc_sig_keyword(desc_sig_element, _sig_element=True):
     """Node for a general keyword in a signature."""
 
-    classes = ["k"]
+    classes = ['k']
 
 
 class desc_sig_keyword_type(desc_sig_element, _sig_element=True):
     """Node for a keyword which is a built-in type in a signature."""
 
-    classes = ["kt"]
+    classes = ['kt']
 
 
 class desc_sig_literal_number(desc_sig_element, _sig_element=True):
     """Node for a numeric literal in a signature."""
 
-    classes = ["m"]
+    classes = ['m']
 
 
 class desc_sig_literal_string(desc_sig_element, _sig_element=True):
     """Node for a string literal in a signature."""
 
-    classes = ["s"]
+    classes = ['s']
 
 
 class desc_sig_literal_char(desc_sig_element, _sig_element=True):
     """Node for a character literal in a signature."""
 
-    classes = ["sc"]
+    classes = ['sc']
 
 
 ###############################################################
 # new admonition-like constructs
 
+
 class versionmodified(nodes.Admonition, nodes.TextElement):
     """Node for version change entries.
 
@@ -411,6 +424,7 @@ class production(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 # other directive-level nodes
 
+
 class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
     """Node for index entries.
 
@@ -422,7 +436,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
     *key* is categorization characters (usually a single character) for
     general index page. For the details of this, please see also:
-    :rst:dir:`glossary` and issue #2320.
+    :rst:dir:`glossary` and https://github.com/sphinx-doc/sphinx/pull/2320.
     """
 
 
@@ -458,6 +472,7 @@ class only(nodes.Element):
 
 # meta-information nodes
 
+
 class start_of_file(nodes.Element):
     """Node to mark start of a new file, used in the LaTeX builder only."""
 
@@ -474,6 +489,7 @@ class tabular_col_spec(nodes.Element):
 
 # inline nodes
 
+
 class pending_xref(nodes.Inline, nodes.Element):
     """Node for cross-references that cannot be resolved without complete
     information about all documents.