Merge branch 'master' into dependabot/pip/mypy-1.16.1

Author: adamtheturtle

.gitattributes

@@ -51,6 +51,8 @@ tests/roots/test-pycode/cp_1251_coded.py dos
 
 # Non UTF-8 encodings
 tests/roots/test-pycode/cp_1251_coded.py working-tree-encoding=windows-1251
+tests/roots/test-root/wrongenc.inc working-tree-encoding=latin-1
+tests/roots/test-warnings/wrongenc.inc working-tree-encoding=latin-1
 
 # Generated files
 # https://github.com/github/linguist/blob/master/docs/overrides.md

CHANGES.rst

@@ -26,6 +26,14 @@ Deprecated
 * #13665: Deprecate support for non-UTF 8 source encodings,
   scheduled for removal in Sphinx 10.
   Patch by Adam Turner.
+* #13679: Non-decodable characters in source files will raise an error in Sphinx 9.
+  Currently, such bytes are replaced with '?' along with logging a warning.
+  Patch by Adam Turner.
+* #13682: Deprecate :py:mod:`!sphinx.io`.
+  Sphinx no longer uses the :py:mod:`!sphinx.io` classes,
+  having replaced them with standard Python I/O.
+  The entire :py:mod:`!sphinx.io` module will be removed in Sphinx 10.
+  Patch by Adam Turner.
 
 Features added
 --------------
@@ -46,10 +54,18 @@ Features added
   Patch by Adam Turner.
 * #13647: LaTeX: allow more cases of table nesting.
   Patch by Jean-François B.
+* #13684: intersphinx: Add a file-based cache for remote inventories.
+  The location of the cache directory must not be relied upon externally,
+  as it may change without notice or warning in future releases.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
 
+* #11498: LaTeX: Table in cell fails to build if it has many rows.
+  Patch by Jean-François B.
+* #11515: LaTeX: longtable does not allow nested table.
+  Patch by Jean-François B.
 * #12821: LaTeX: URLs/links in section titles should render in PDF.
   Patch by Jean-François B.
 * #13369: Correctly parse and cross-reference unpacked type annotations.
@@ -65,6 +81,8 @@ Bugs fixed
 * #13635: LaTeX: if a cell contains a table, row coloring is turned off for
   the next table cells.
   Patch by Jean-François B.
+* #13685: gettext: Correctly ignore trailing backslashes.
+  Patch by Bénédikt Tran.
 
 Testing
 -------

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - Removed
      - Alternatives
 
+   * - ``sphinx.io`` (entire module)
+     - 8.3
+     - 10.0
+     - ``docutils.io`` or standard Python I/O
+
    * - ``sphinx.builders.Builder.app``
      - 8.3
      - 10.0

doc/usage/domains/index.rst

@@ -35,6 +35,69 @@ easier to write.
 This section describes what the domains that are included with Sphinx provide.
 The domain API is documented as well, in the section :ref:`domain-api`.
 
+Built-in domains
+----------------
+
+The following domains are included within Sphinx:
+
+.. toctree::
+   :maxdepth: 1
+
+   standard
+   c
+   cpp
+   javascript
+   mathematics
+   python
+   restructuredtext
+
+
+Third-party domains
+-------------------
+
+Several third-party domains are available as extensions, including:
+
+* `Ada <https://pypi.org/project/sphinxcontrib-adadomain/>`__
+* `Antlr4 <https://pypi.org/project/sphinx-a4doc/>`__
+* `Bazel <https://pypi.org/project/sphinx-bazel/>`__
+* `BibTex <https://pypi.org/project/sphinxcontrib-bibtex/>`__
+* `Chapel <https://pypi.org/project/sphinxcontrib-chapeldomain/>`__
+* `CMake <https://pypi.org/project/sphinxcontrib-moderncmakedomain/>`__
+* `Common Lisp <https://pypi.org/project/sphinxcontrib-cldomain/>`__
+* `Erlang <https://pypi.org/project/sphinxcontrib-erlangdomain/>`__
+* `Fortran <https://pypi.org/project/sphinx-fortran/>`__
+* `GraphQL <https://pypi.org/project/graphqldomain/>`__
+* `Go <https://pypi.org/project/sphinxcontrib-golangdomain/>`__
+* `HTTP <https://pypi.org/project/sphinxcontrib-httpdomain/>`__
+* `Hy <https://pypi.org/project/sphinxcontrib-hydomain/>`__
+* `Lua <https://pypi.org/project/sphinxcontrib-luadomain/>`__
+* `MATLAB <https://pypi.org/project/sphinxcontrib-matlabdomain/>`__
+* `PHP <https://pypi.org/project/sphinxcontrib-phpdomain/>`__
+* `Ruby <https://pypi.org/project/sphinxcontrib-rubydomain/>`__
+* `Rust <https://pypi.org/project/sphinxcontrib-rust/>`__
+* `Verilog <https://pypi.org/project/sphinx-verilog-domain/>`__
+* `VHDL <https://pypi.org/project/sphinx-vhdl/>`__
+* `Visual Basic <https://pypi.org/project/sphinx-vb-domain/>`__
+
+Other domains may be found on the Python Package Index
+(via the `Framework :: Sphinx :: Domain`__ classifier),
+`GitHub <https://github.com/search?q=sphinx%20domain&type=repositories>`__, or
+`GitLab <https://gitlab.com/explore/projects?name=sphinx%20domain>`__.
+
+__ https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Domain
+
+.. NOTE: The following all seem unmaintained, last released 2018 or earlier.
+         The links are preserved in this comment for reference.
+
+   * `CoffeeScript <https://pypi.org/project/sphinxcontrib-coffee/>`__
+   * `DotNET <https://pypi.org/project/sphinxcontrib-dotnetdomain/>`__
+   * `dqn <https://pypi.org/project/sphinxcontrib-dqndomain/>`__
+   * `Jinja <https://pypi.org/project/sphinxcontrib-jinjadomain/>`__
+   * `JSON <https://pypi.org/project/sphinx-jsondomain/>`__
+   * `Lasso <https://pypi.org/project/sphinxcontrib-lassodomain/>`__
+   * `Operation <https://pypi.org/project/sphinxcontrib-operationdomain/>`__
+   * `Scala <https://pypi.org/project/sphinxcontrib-scaladomain/>`__
+
 
 .. _basic-domain-markup:
 
@@ -174,40 +237,3 @@ In short:
   component of the target.
   For example, ``:py:meth:`~queue.Queue.get``` will
   refer to ``queue.Queue.get`` but only display ``get`` as the link text.
-
-Built-in domains
-----------------
-
-The following domains are included within Sphinx:
-
-.. toctree::
-   :maxdepth: 1
-
-   standard
-   c
-   cpp
-   javascript
-   mathematics
-   python
-   restructuredtext
-
-More domains
-------------
-
-There are several third-party domains available as extensions, including:
-
-* `Ada <https://pypi.org/project/sphinxcontrib-adadomain/>`__
-* `Chapel <https://pypi.org/project/sphinxcontrib-chapeldomain/>`__
-* `CoffeeScript <https://pypi.org/project/sphinxcontrib-coffee/>`__
-* `Common Lisp <https://pypi.org/project/sphinxcontrib-cldomain/>`__
-* `dqn <https://pypi.org/project/sphinxcontrib-dqndomain/>`__
-* `Erlang <https://pypi.org/project/sphinxcontrib-erlangdomain/>`__
-* `Go <https://pypi.org/project/sphinxcontrib-golangdomain/>`__
-* `HTTP <https://pypi.org/project/sphinxcontrib-httpdomain/>`__
-* `Jinja <https://pypi.org/project/sphinxcontrib-jinjadomain/>`__
-* `Lasso <https://pypi.org/project/sphinxcontrib-lassodomain/>`__
-* `MATLAB <https://pypi.org/project/sphinxcontrib-matlabdomain/>`__
-* `Operation <https://pypi.org/project/sphinxcontrib-operationdomain/>`__
-* `PHP <https://pypi.org/project/sphinxcontrib-phpdomain/>`__
-* `Ruby <https://pypi.org/project/sphinxcontrib-rubydomain/>`__
-* `Scala <https://pypi.org/project/sphinxcontrib-scaladomain/>`__

pyproject.toml

@@ -304,7 +304,6 @@ module = [
     # tests/test_config
     "tests.test_config.test_config",
     # tests/test_directives
-    "tests.test_directives.test_directive_only",
     "tests.test_directives.test_directive_other",
     "tests.test_directives.test_directive_patch",
     # tests/test_domains

sphinx/builders/__init__.py

@@ -11,7 +11,6 @@
 from typing import TYPE_CHECKING, final
 
 from docutils import nodes
-from docutils.utils import DependencyList
 
 from sphinx._cli.util.colour import bold
 from sphinx.deprecation import _deprecation_warning
@@ -23,16 +22,12 @@
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import SphinxError
 from sphinx.locale import __
-from sphinx.util import (
-    get_filetype,
-    logging,
-    rst,
-)
+from sphinx.util import get_filetype, logging
 from sphinx.util._importer import import_object
 from sphinx.util._pathlib import _StrPathProperty
 from sphinx.util.build_phase import BuildPhase
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import sphinx_domains
+from sphinx.util.docutils import _parse_str_to_doctree
 from sphinx.util.i18n import CatalogRepository, docname_to_domain
 from sphinx.util.osutil import ensuredir, relative_uri, relpath
 from sphinx.util.parallel import (
@@ -644,26 +639,34 @@ def read_doc(self, docname: str, *, _cache: bool = True) -> None:
         if docutils_conf.is_file():
             env.note_dependency(docutils_conf)
 
-        filename = str(env.doc2path(docname))
-        filetype = get_filetype(self._app.config.source_suffix, filename)
-        publisher = self._registry._get_publisher(
-            filetype, config=self.config, env=self.env
+        filename = env.doc2path(docname)
+
+        # set up error_handler for the target document
+        # xref RemovedInSphinx90Warning
+        error_handler = _UnicodeDecodeErrorHandler(docname)
+        codecs.register_error('sphinx', error_handler)  # type: ignore[arg-type]
+
+        # read the source file
+        content = filename.read_text(
+            encoding=env.settings['input_encoding'], errors='sphinx'
         )
-        self.env.current_document._parser = publisher.parser
-        # record_dependencies is mutable even though it is in settings,
-        # explicitly re-initialise for each document
-        publisher.settings.record_dependencies = DependencyList()
-        with (
-            sphinx_domains(env),
-            rst.default_role(docname, self.config.default_role),
-        ):
-            # set up error_handler for the target document
-            error_handler = _UnicodeDecodeErrorHandler(docname)
-            codecs.register_error('sphinx', error_handler)  # type: ignore[arg-type]
 
-            publisher.set_source(source_path=filename)
-            publisher.publish()
-            doctree = publisher.document
+        # TODO: move the "source-read" event to here.
+
+        filetype = get_filetype(self.config.source_suffix, filename)
+        parser = self._registry.create_source_parser(
+            filetype, config=self.config, env=env
+        )
+        doctree = _parse_str_to_doctree(
+            content,
+            filename=filename,
+            default_role=self.config.default_role,
+            default_settings=env.settings,
+            env=env,
+            events=self.events,
+            parser=parser,
+            transforms=self._registry.get_transforms(),
+        )
 
         # store time of reading, for outdated files detection
         env.all_docs[docname] = time.time_ns() // 1_000
@@ -901,20 +904,21 @@ def __init__(self, docname: str, /) -> None:
         self.docname = docname
 
     def __call__(self, error: UnicodeDecodeError) -> tuple[str, int]:
-        line_start = error.object.rfind(b'\n', 0, error.start)
-        line_end = error.object.find(b'\n', error.start)
+        obj = error.object
+        line_start = obj.rfind(b'\n', 0, error.start)
+        line_end = obj.find(b'\n', error.start)
         if line_end == -1:
-            line_end = len(error.object)
-        line_num = error.object.count(b'\n', 0, error.start) + 1
+            line_end = len(obj)
+        line_num = obj.count(b'\n', 0, error.start) + 1
         logger.warning(
-            __('undecodable source characters, replacing with "?": %r'),
-            (
-                error.object[line_start + 1 : error.start]
-                + b'>>>'
-                + error.object[error.start : error.end]
-                + b'<<<'
-                + error.object[error.end : line_end]
+            __(
+                "undecodable source characters, replacing with '?': '%s>>>%s<<<%s'. "
+                'This will become an error in Sphinx 9.0.'
+                # xref RemovedInSphinx90Warning
             ),
+            obj[line_start + 1 : error.start].decode(errors='backslashreplace'),
+            obj[error.start : error.end].decode(errors='backslashreplace'),
+            obj[error.end : line_end].decode(errors='backslashreplace'),
             location=(self.docname, line_num),
         )
         return '?', error.end