Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/builders/singlehtml.py

@@ -2,21 +2,23 @@
 
 from __future__ import annotations
 
-from os import path
-from typing import TYPE_CHECKING, Any
+import warnings
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 
+from sphinx._cli.util.colour import darkgreen
 from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.deprecation import RemovedInSphinx10Warning
 from sphinx.environment.adapters.toctree import global_toctree_for_doc
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 
 if TYPE_CHECKING:
     from collections.abc import Set
+    from typing import Any
 
     from docutils.nodes import Node
 
@@ -27,10 +29,7 @@ logger = logging.getLogger(__name__)
 
 
 class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
-    """
-    A StandaloneHTMLBuilder subclass that puts the whole document tree on one
-    HTML page.
-    """
+    """Builds the whole document tree as a single HTML page."""
 
     name = 'singlehtml'
     epilog = __('The HTML page is in %(outdir)s.')
@@ -53,6 +52,14 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         return self.get_target_uri(to, typ)
 
     def fix_refuris(self, tree: Node) -> None:
+        deprecation_msg = (
+            "The 'SingleFileHTMLBuilder.fix_refuris' method is no longer used "
+            'within the builder and is planned for removal in Sphinx 10. '
+            'Please report malformed URIs generated by the Sphinx singlehtml '
+            'builder as bugreports.'
+        )
+        warnings.warn(deprecation_msg, RemovedInSphinx10Warning, stacklevel=2)
+
         # fix refuris with double anchor
         for refnode in tree.findall(nodes.reference):
             if 'refuri' not in refnode:
@@ -74,13 +81,11 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
                 kwargs['includehidden'] = False
             elif includehidden.lower() == 'true':
                 kwargs['includehidden'] = True
-        if kwargs.get('maxdepth') == '':
+        if kwargs.get('maxdepth') == '':  # NoQA: PLC1901
             kwargs.pop('maxdepth')
         toctree = global_toctree_for_doc(
             self.env, docname, self, collapse=collapse, **kwargs
         )
-        if toctree is not None:
-            self.fix_refuris(toctree)
         return self.render_partial(toctree)['fragment']
 
     def assemble_doctree(self) -> nodes.document:
@@ -90,7 +95,6 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master])
         tree['docname'] = master
         self.env.resolve_references(tree, master, self)
-        self.fix_refuris(tree)
         return tree
 
     def assemble_toc_secnumbers(self) -> dict[str, dict[str, tuple[int, ...]]]:
@@ -141,7 +145,6 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         )
         # if there is no toctree, toc is None
         if toctree:
-            self.fix_refuris(toctree)
             toc = self.render_partial(toctree)['fragment']
             display_toc = True
         else:
@@ -189,20 +192,29 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
 
         # additional pages from conf.py
         for pagename, template in self.config.html_additional_pages.items():
-            logger.info(' ' + pagename, nonl=True)
+            logger.info(' %s', pagename, nonl=True)
             self.handle_page(pagename, {}, template)
 
         if self.config.html_use_opensearch:
             logger.info(' opensearch', nonl=True)
-            fn = path.join(self.outdir, '_static', 'opensearch.xml')
-            self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
+            self.handle_page(
+                'opensearch',
+                {},
+                'opensearch.xml',
+                outfilename=self._static_dir / 'opensearch.xml',
+            )
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.setup_extension('sphinx.builders.html')
 
     app.add_builder(SingleFileHTMLBuilder)
-    app.add_config_value('singlehtml_sidebars', lambda self: self.html_sidebars, 'html')
+    app.add_config_value(
+        'singlehtml_sidebars',
+        lambda self: self.html_sidebars,
+        'html',
+        types=frozenset({dict}),
+    )
 
     return {
         'version': 'builtin',

sphinx/builders/texinfo.py

@@ -2,22 +2,21 @@
 
 from __future__ import annotations
 
-import os
+import os.path
 import warnings
-from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.frontend import OptionParser
 from docutils.io import FileOutput
 
 from sphinx import addnodes, package_dir
+from sphinx._cli.util.colour import darkgreen
 from sphinx.builders import Builder
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import new_document
 from sphinx.util.nodes import inline_all_toctrees
@@ -26,6 +25,7 @@ from sphinx.writers.texinfo import TexinfoTranslator, TexinfoWriter
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Set
+    from typing import Any
 
     from docutils.nodes import Node
 
@@ -34,13 +34,11 @@ if TYPE_CHECKING:
     from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
-template_dir = os.path.join(package_dir, 'templates', 'texinfo')
+template_dir = package_dir.joinpath('templates', 'texinfo')
 
 
 class TexinfoBuilder(Builder):
-    """
-    Builds Texinfo output to create Info documentation.
-    """
+    """Builds Texinfo output to create Info documentation."""
 
     name = 'texinfo'
     format = 'texinfo'
@@ -109,7 +107,8 @@ class TexinfoBuilder(Builder):
             if len(entry) > 7:
                 toctree_only = entry[7]
             destination = FileOutput(
-                destination_path=path.join(self.outdir, targetname), encoding='utf-8'
+                destination_path=self.outdir / targetname,
+                encoding='utf-8',
             )
             with progress_message(__('processing %s') % targetname, nonl=False):
                 appendices = self.config.texinfo_appendices or []
@@ -185,8 +184,6 @@ class TexinfoBuilder(Builder):
                         nodes.Text(')'),
                     ))
                     break
-            else:
-                pass
             pendingnode.replace_self(newnodes)
         return largetree
 
@@ -195,7 +192,7 @@ class TexinfoBuilder(Builder):
 
     def copy_image_files(self, targetname: str) -> None:
         if self.images:
-            stringify_func = ImageAdapter(self.app.env).get_original_image_uri
+            stringify_func = ImageAdapter(self.env).get_original_image_uri
             for src in status_iterator(
                 self.images,
                 __('copying images... '),
@@ -216,7 +213,7 @@ class TexinfoBuilder(Builder):
                 except Exception as err:
                     logger.warning(
                         __('cannot copy image file %r: %s'),
-                        path.join(self.srcdir, src),
+                        self.srcdir / src,
                         err,
                     )
 
@@ -225,7 +222,7 @@ class TexinfoBuilder(Builder):
             with progress_message(__('copying Texinfo support files')):
                 logger.info('Makefile ', nonl=True)
                 copyfile(
-                    os.path.join(template_dir, 'Makefile'),
+                    template_dir / 'Makefile',
                     self.outdir / 'Makefile',
                     force=True,
                 )
@@ -254,13 +251,23 @@ def default_texinfo_documents(
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(TexinfoBuilder)
 
-    app.add_config_value('texinfo_documents', default_texinfo_documents, '')
-    app.add_config_value('texinfo_appendices', [], '')
-    app.add_config_value('texinfo_elements', {}, '')
-    app.add_config_value('texinfo_domain_indices', True, '', types={set, list})
-    app.add_config_value('texinfo_show_urls', 'footnote', '')
-    app.add_config_value('texinfo_no_detailmenu', False, '')
-    app.add_config_value('texinfo_cross_references', True, '')
+    app.add_config_value(
+        'texinfo_documents',
+        default_texinfo_documents,
+        '',
+        types=frozenset({list, tuple}),
+    )
+    app.add_config_value('texinfo_appendices', [], '', types=frozenset({list, tuple}))
+    app.add_config_value('texinfo_elements', {}, '', types=frozenset({dict}))
+    app.add_config_value(
+        'texinfo_domain_indices',
+        True,
+        '',
+        types=frozenset({frozenset, list, set, tuple}),
+    )
+    app.add_config_value('texinfo_show_urls', 'footnote', '', types=frozenset({str}))
+    app.add_config_value('texinfo_no_detailmenu', False, '', types=frozenset({bool}))
+    app.add_config_value('texinfo_cross_references', True, '', types=frozenset({bool}))
 
     return {
         'version': 'builtin',

sphinx/builders/text.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from os import path
 from typing import TYPE_CHECKING
 
 from docutils.io import StringOutput
@@ -10,11 +9,7 @@ from docutils.io import StringOutput
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.osutil import (
-    _last_modified_time,
-    ensuredir,
-    os_path,
-)
+from sphinx.util.osutil import _last_modified_time
 from sphinx.writers.text import TextTranslator, TextWriter
 
 if TYPE_CHECKING:
@@ -48,7 +43,7 @@ class TextBuilder(Builder):
             if docname not in self.env.all_docs:
                 yield docname
                 continue
-            targetname = path.join(self.outdir, docname + self.out_suffix)
+            targetname = self.outdir / (docname + self.out_suffix)
             try:
                 targetmtime = _last_modified_time(targetname)
             except Exception:
@@ -72,13 +67,13 @@ class TextBuilder(Builder):
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
         destination = StringOutput(encoding='utf-8')
         self.writer.write(doctree, destination)
-        outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix)
-        ensuredir(path.dirname(outfilename))
+        out_file_name = self.outdir / (docname + self.out_suffix)
+        out_file_name.parent.mkdir(parents=True, exist_ok=True)
         try:
-            with open(outfilename, 'w', encoding='utf-8') as f:
+            with open(out_file_name, 'w', encoding='utf-8') as f:
                 f.write(self.writer.output)
         except OSError as err:
-            logger.warning(__('error writing file %s: %s'), outfilename, err)
+            logger.warning(__('error writing file %s: %s'), out_file_name, err)
 
     def finish(self) -> None:
         pass
@@ -87,10 +82,10 @@ class TextBuilder(Builder):
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(TextBuilder)
 
-    app.add_config_value('text_sectionchars', '*=-~"+`', 'env')
-    app.add_config_value('text_newlines', 'unix', 'env')
-    app.add_config_value('text_add_secnumbers', True, 'env')
-    app.add_config_value('text_secnumber_suffix', '. ', 'env')
+    app.add_config_value('text_sectionchars', '*=-~"+`', 'env', types=frozenset({str}))
+    app.add_config_value('text_newlines', 'unix', 'env', types=frozenset({str}))
+    app.add_config_value('text_add_secnumbers', True, 'env', types=frozenset({bool}))
+    app.add_config_value('text_secnumber_suffix', '. ', 'env', types=frozenset({str}))
 
     return {
         'version': 'builtin',

sphinx/builders/xml.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from os import path
 from typing import TYPE_CHECKING
 
 from docutils import nodes
@@ -12,11 +11,7 @@ from docutils.writers.docutils_xml import XMLTranslator
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.osutil import (
-    _last_modified_time,
-    ensuredir,
-    os_path,
-)
+from sphinx.util.osutil import _last_modified_time
 from sphinx.writers.xml import PseudoXMLWriter, XMLWriter
 
 if TYPE_CHECKING:
@@ -29,9 +24,7 @@ logger = logging.getLogger(__name__)
 
 
 class XMLBuilder(Builder):
-    """
-    Builds Docutils-native XML.
-    """
+    """Builds Docutils-native XML."""
 
     name = 'xml'
     format = 'xml'
@@ -40,7 +33,7 @@ class XMLBuilder(Builder):
     out_suffix = '.xml'
     allow_parallel = True
 
-    _writer_class: type[XMLWriter] | type[PseudoXMLWriter] = XMLWriter
+    _writer_class: type[XMLWriter | PseudoXMLWriter] = XMLWriter
     writer: XMLWriter | PseudoXMLWriter
     default_translator_class = XMLTranslator
 
@@ -52,7 +45,7 @@ class XMLBuilder(Builder):
             if docname not in self.env.all_docs:
                 yield docname
                 continue
-            targetname = path.join(self.outdir, docname + self.out_suffix)
+            targetname = self.outdir / (docname + self.out_suffix)
             try:
                 targetmtime = _last_modified_time(targetname)
             except Exception:
@@ -88,22 +81,20 @@ class XMLBuilder(Builder):
                             value[i] = list(val)
         destination = StringOutput(encoding='utf-8')
         self.writer.write(doctree, destination)
-        outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix)
-        ensuredir(path.dirname(outfilename))
+        out_file_name = self.outdir / (docname + self.out_suffix)
+        out_file_name.parent.mkdir(parents=True, exist_ok=True)
         try:
-            with open(outfilename, 'w', encoding='utf-8') as f:
+            with open(out_file_name, 'w', encoding='utf-8') as f:
                 f.write(self.writer.output)
         except OSError as err:
-            logger.warning(__('error writing file %s: %s'), outfilename, err)
+            logger.warning(__('error writing file %s: %s'), out_file_name, err)
 
     def finish(self) -> None:
         pass
 
 
 class PseudoXMLBuilder(XMLBuilder):
-    """
-    Builds pseudo-XML for display purposes.
-    """
+    """Builds pseudo-XML for display purposes."""
 
     name = 'pseudoxml'
     format = 'pseudoxml'
@@ -118,7 +109,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(XMLBuilder)
     app.add_builder(PseudoXMLBuilder)
 
-    app.add_config_value('xml_pretty', True, 'env')
+    app.add_config_value('xml_pretty', True, 'env', types=frozenset({bool}))
 
     return {
         'version': 'builtin',

sphinx/cmd/build.py

@@ -3,36 +3,29 @@
 from __future__ import annotations
 
 import argparse
-import bdb
 import contextlib
 import locale
 import multiprocessing
-import os
-import pdb  # NoQA: T100
 import sys
-import traceback
-from os import path
-from typing import TYPE_CHECKING, Any, TextIO
-
-from docutils.utils import SystemMessage
+from pathlib import Path
+from typing import TYPE_CHECKING
 
+import sphinx._cli.util.errors
 import sphinx.locale
 from sphinx import __display_version__
+from sphinx._cli.util.colour import disable_colour, terminal_supports_colour
 from sphinx.application import Sphinx
-from sphinx.errors import SphinxError, SphinxParallelError
 from sphinx.locale import __
 from sphinx.util._io import TeeStripANSI
-from sphinx.util.console import color_terminal, nocolor, red, terminal_safe
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.docutils import docutils_namespace, patch_docutils
-from sphinx.util.exceptions import format_exception_cut_frames, save_traceback
 from sphinx.util.osutil import ensuredir
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
-    from typing import Protocol
+    from collections.abc import Collection, Sequence
+    from typing import Any, TextIO
 
-    class SupportsWrite(Protocol):
-        def write(self, text: str, /) -> int | None: ...  # NoQA: E704
+    from sphinx.extension import Extension
 
 
 def handle_exception(
@@ -41,99 +34,26 @@ def handle_exception(
     exception: BaseException,
     stderr: TextIO = sys.stderr,
 ) -> None:
-    if isinstance(exception, bdb.BdbQuit):
-        return
-
-    if args.pdb:
-        print(
-            red(__('Exception occurred while building, starting debugger:')),
-            file=stderr,
-        )
-        traceback.print_exc()
-        pdb.post_mortem(sys.exc_info()[2])
+    if app is not None:
+        message_log: Sequence[str] = app.messagelog
+        extensions: Collection[Extension] = app.extensions.values()
     else:
-        print(file=stderr)
-        if args.verbosity or args.traceback:
-            exc = sys.exc_info()[1]
-            if isinstance(exc, SphinxParallelError):
-                exc_format = '(Error in parallel process)\n' + exc.traceback
-                print(exc_format, file=stderr)
-            else:
-                traceback.print_exc(None, stderr)
-                print(file=stderr)
-        if isinstance(exception, KeyboardInterrupt):
-            print(__('Interrupted!'), file=stderr)
-        elif isinstance(exception, SystemMessage):
-            print(red(__('reST markup error:')), file=stderr)
-            print(terminal_safe(exception.args[0]), file=stderr)
-        elif isinstance(exception, SphinxError):
-            print(red('%s:' % exception.category), file=stderr)
-            print(str(exception), file=stderr)
-        elif isinstance(exception, UnicodeError):
-            print(red(__('Encoding error:')), file=stderr)
-            print(terminal_safe(str(exception)), file=stderr)
-            tbpath = save_traceback(app, exception)
-            print(
-                red(
-                    __(
-                        'The full traceback has been saved in %s, if you want '
-                        'to report the issue to the developers.'
-                    )
-                    % tbpath
-                ),
-                file=stderr,
-            )
-        elif (
-            isinstance(exception, RuntimeError)
-            and 'recursion depth' in str(exception)
-        ):  # fmt: skip
-            print(red(__('Recursion error:')), file=stderr)
-            print(terminal_safe(str(exception)), file=stderr)
-            print(file=stderr)
-            print(
-                __(
-                    '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.:'
-                ),
-                file=stderr,
-            )
-            print('    import sys; sys.setrecursionlimit(1500)', file=stderr)
-        else:
-            print(red(__('Exception occurred:')), file=stderr)
-            print(format_exception_cut_frames().rstrip(), file=stderr)
-            tbpath = save_traceback(app, exception)
-            print(
-                red(
-                    __(
-                        'The full traceback has been saved in %s, if you '
-                        'want to report the issue to the developers.'
-                    )
-                    % tbpath
-                ),
-                file=stderr,
-            )
-            print(
-                __(
-                    'Please also report this if it was a user error, so '
-                    'that a better error message can be provided next time.'
-                ),
-                file=stderr,
-            )
-            print(
-                __(
-                    'A bug report can be filed in the tracker at '
-                    '<https://github.com/sphinx-doc/sphinx/issues>. Thanks!'
-                ),
-                file=stderr,
-            )
+        message_log = extensions = ()
+    return sphinx._cli.util.errors.handle_exception(
+        exception,
+        stderr=stderr,
+        use_pdb=args.pdb,
+        print_traceback=args.verbosity or args.traceback,
+        message_log=message_log,
+        extensions=extensions,
+    )
 
 
 def jobs_argument(value: str) -> int:
-    """
-    Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can
-    be expanded to handle other special scaling requests, such as setting job count
-    to cpu_count.
+    """Parse the ``--jobs`` flag.
+
+    Return the number of CPUs if 'auto' is used,
+    otherwise ensure *value* is a positive integer.
     """
     if value == 'auto':
         return multiprocessing.cpu_count()
@@ -217,14 +137,14 @@ files can be built by specifying individual filenames.
         '-a',
         action='store_true',
         dest='force_all',
-        help=__('write all files (default: only write new and ' 'changed files)'),
+        help=__('write all files (default: only write new and changed files)'),
     )
     group.add_argument(
         '--fresh-env',
         '-E',
         action='store_true',
         dest='freshenv',
-        help=__("don't use a saved environment, always read " 'all files'),
+        help=__("don't use a saved environment, always read all files"),
     )
 
     group = parser.add_argument_group(__('path options'))
@@ -243,9 +163,7 @@ files can be built by specifying individual filenames.
         '-c',
         metavar='PATH',
         dest='confdir',
-        help=__(
-            'directory for the configuration file (conf.py) ' '(default: SOURCE_DIR)'
-        ),
+        help=__('directory for the configuration file (conf.py) (default: SOURCE_DIR)'),
     )
 
     group = parser.add_argument_group('build configuration options')
@@ -392,10 +310,10 @@ def _parse_confdir(noconfig: bool, confdir: str, sourcedir: str) -> str | None:
     return confdir
 
 
-def _parse_doctreedir(doctreedir: str, outputdir: str) -> str:
+def _parse_doctreedir(doctreedir: str, outputdir: str) -> _StrPath:
     if doctreedir:
-        return doctreedir
-    return os.path.join(outputdir, '.doctrees')
+        return _StrPath(doctreedir)
+    return _StrPath(outputdir, '.doctrees')
 
 
 def _validate_filenames(
@@ -408,8 +326,8 @@ def _validate_filenames(
 
 
 def _validate_colour_support(colour: str) -> None:
-    if colour == 'no' or (colour == 'auto' and not color_terminal()):
-        nocolor()
+    if colour == 'no' or (colour == 'auto' and not terminal_supports_colour()):
+        disable_colour()
 
 
 def _parse_logging(
@@ -431,12 +349,12 @@ def _parse_logging(
     warnfp = None
     if warning and warnfile:
         try:
-            warnfile = path.abspath(warnfile)
-            ensuredir(path.dirname(warnfile))
+            warn_file = Path(warnfile).resolve()
+            ensuredir(warn_file.parent)
             # the caller is responsible for closing this file descriptor
-            warnfp = open(warnfile, 'w', encoding='utf-8')  # NoQA: SIM115
+            warnfp = open(warn_file, 'w', encoding='utf-8')  # NoQA: SIM115
         except Exception as exc:
-            parser.error(__('cannot open warning file %r: %s') % (warnfile, exc))
+            parser.error(__("cannot open warning file '%s': %s") % (warn_file, exc))
         warning = TeeStripANSI(warning, warnfp)  # type: ignore[assignment]
         error = warning
 
@@ -514,7 +432,19 @@ def build_main(argv: Sequence[str]) -> int:
             app.build(args.force_all, args.filenames)
             return app.statuscode
     except (Exception, KeyboardInterrupt) as exc:
-        handle_exception(app, args, exc, args.error)
+        if app is not None:
+            message_log: Sequence[str] = app.messagelog
+            extensions: Collection[Extension] = app.extensions.values()
+        else:
+            message_log = extensions = ()
+        sphinx._cli.util.errors.handle_exception(
+            exc,
+            stderr=args.error,
+            use_pdb=args.pdb,
+            print_traceback=args.verbosity or args.traceback,
+            message_log=message_log,
+            extensions=extensions,
+        )
         return 2
     finally:
         if warnfp is not None: