Merge branch 'master' into coverage-all-modules

AA-Turner · AA-Turner · commit 732de74b8579 · 2023-09-20T21:44:23.000+01:00
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -102,7 +102,9 @@ jobs:
         sphinx-lint
         --enable line-too-long
         --max-line-length 85 
-        CHANGES
+        AUTHORS.rst
+        CHANGES.rst
+        CODE_OF_CONDUCT.rst
         CONTRIBUTING.rst
         README.rst
         doc/
diff --git a/AUTHORS.rst b/AUTHORS.rst
diff --git a/CHANGES.rst b/CHANGES.rst
diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst
diff --git a/EXAMPLES.rst b/EXAMPLES.rst
diff --git a/LICENSE.rst b/LICENSE.rst
diff --git a/Makefile b/Makefile
@@ -49,7 +49,7 @@ type-check:
 
 .PHONY: doclinter
 doclinter:
-	sphinx-lint --enable line-too-long --max-line-length 85 CHANGES *.rst doc/
+	sphinx-lint --enable line-too-long --max-line-length 85 *.rst doc/
 
 .PHONY: test
 test:
diff --git a/doc/authors.rst b/doc/authors.rst
@@ -6,4 +6,4 @@
 Sphinx authors
 ==============
 
-.. include:: ../AUTHORS
+.. include:: ../AUTHORS.rst
diff --git a/doc/changes.rst b/doc/changes.rst
@@ -19,4 +19,4 @@ Changelog
    \makeatother
 
 
-.. include:: ../CHANGES
+.. include:: ../CHANGES.rst
diff --git a/doc/conf.py b/doc/conf.py
@@ -6,6 +6,8 @@
 
 import sphinx
 
+os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
+
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
               'sphinx.ext.autosummary', 'sphinx.ext.extlinks',
               'sphinx.ext.intersphinx',
@@ -210,7 +212,7 @@ def linkify_issues_in_changelog(app, docname, source):
     """ Linkify issue references like #123 in changelog to GitHub. """
 
     if docname == 'changes':
-        changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
+        changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES.rst")
         # this path trickery is needed because this script can
         # be invoked with different working directories:
         # * running make in docs/
@@ -225,7 +227,7 @@ def linkify(match):
 
         linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog)
 
-        source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
+        source[0] = source[0].replace('.. include:: ../CHANGES.rst', linkified_changelog)
 
 
 def setup(app):
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -2,4 +2,4 @@
 
 .. _examples:
 
-.. include:: ../EXAMPLES
+.. include:: ../EXAMPLES.rst
diff --git a/doc/internals/code-of-conduct.rst b/doc/internals/code-of-conduct.rst
@@ -2,4 +2,4 @@
 
 .. _code_of_conduct:
 
-.. include:: ../../CODE_OF_CONDUCT
+.. include:: ../../CODE_OF_CONDUCT.rst
diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst
@@ -114,7 +114,7 @@ These are the basic steps needed to start developing on Sphinx.
    Write your code along with tests that shows that the bug was fixed or that
    the feature works as expected.
 
-#. Add a bullet point to :file:`CHANGES` if the fix or feature is not trivial
+#. Add a bullet point to :file:`CHANGES.rst` if the fix or feature is not trivial
    (small doc updates, typo fixes), then commit::
 
        git commit -m '#42: Add useful new feature that does this.'
@@ -142,7 +142,7 @@ Please follow these guidelines when writing code for Sphinx:
 
 * Try to use the same code style as used in the rest of the project.
 
-* For non-trivial changes, please update the :file:`CHANGES` file.  If your
+* For non-trivial changes, please update the :file:`CHANGES.rst` file.  If your
   changes alter existing behavior, please document this.
 
 * New features should be documented.  Include examples and use cases where
diff --git a/doc/internals/organization.rst b/doc/internals/organization.rst
@@ -24,7 +24,7 @@ The following are some general guidelines for core developers:
   in a good working state and that all tests pass before pushing your changes.
 
 * When committing code written by someone else, please attribute the original
-  author in the commit message and any relevant :file:`CHANGES` entry.
+  author in the commit message and any relevant :file:`CHANGES.rst` entry.
 
 Membership
 ~~~~~~~~~~
diff --git a/doc/internals/release-process.rst b/doc/internals/release-process.rst
@@ -122,4 +122,4 @@ Date        Python
 Release procedures
 ------------------
 
-The release procedures are listed in ``utils/release-checklist``.
+The release procedures are listed in :file:`utils/release-checklist.rst`.
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
@@ -544,9 +544,9 @@ __ https://pygments.org/docs/lexers
 
           def some_function():
               interesting = False
-              print 'This line is highlighted.'
-              print 'This one is not...'
-              print '...but this one is.'
+              print('This line is highlighted.')
+              print('This one is not...')
+              print('...but this one is.')
 
       .. versionadded:: 1.1
       .. versionchanged:: 1.6.6
@@ -576,7 +576,7 @@ __ https://pygments.org/docs/lexers
            :caption: this.py
            :name: this-py
 
-           print 'Explicit is better than implicit.'
+           print('Explicit is better than implicit.')
 
       In order to cross-reference a code-block using either the
       :rst:role:`ref` or the :rst:role:`numref` role, it is necessary
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
@@ -527,7 +527,7 @@ The following directives are provided for module and class contents:
    .. rst:directive:option:: final
       :type: no value
 
-      Indicate the class is a final method.
+      Indicate the method is a final method.
 
       .. versionadded:: 3.1
 
diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst
@@ -468,8 +468,8 @@ different style:
 
    A piece of literal text, such as code.  Within the contents, you can use
    curly braces to indicate a "variable" part, as in :rst:role:`file`.  For
-   example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be
-   emphasized: :samp:`print 1+{variable}`
+   example, in ``:samp:`print(1+{variable})```, the part ``variable`` would be
+   emphasized: :samp:`print(1+{variable})`
 
    If you don't need the "variable part" indication, use the standard
    :rst:role:`code` role instead.
diff --git a/pyproject.toml b/pyproject.toml
@@ -112,13 +112,13 @@ name = "sphinx"
 
 [tool.flit.sdist]
 include = [
-    "LICENSE",
-    "AUTHORS",
-    "CHANGES",
+    "LICENSE.rst",
+    "AUTHORS.rst",
+    "CHANGES.rst",
     # Documentation
     "doc/",
-    "CODE_OF_CONDUCT",  # used as an include in the Documentation
-    "EXAMPLES",  # used as an include in the Documentation
+    "CODE_OF_CONDUCT.rst",  # used as an include in the Documentation
+    "EXAMPLES.rst",  # used as an include in the Documentation
     # Tests
     "tests/",
     "tox.ini",
diff --git a/sphinx/__init__.py b/sphinx/__init__.py
@@ -19,7 +19,7 @@
 warnings.filterwarnings('ignore', 'The frontend.Option class .*',
                         DeprecationWarning, module='docutils.frontend')
 
-__version__ = '7.2.5'
+__version__ = '7.3.0'
 __display_version__ = __version__  # used for command line version
 
 #: Version info for better programmatic use.
@@ -30,11 +30,11 @@
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (7, 2, 5, 'final', 0)
+version_info = (7, 3, 0, 'beta', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 
-_in_development = False
+_in_development = True
 if _in_development:
     # Only import subprocess if needed
     import subprocess
diff --git a/sphinx/cmd/make_mode.py b/sphinx/cmd/make_mode.py
@@ -67,7 +67,6 @@ def __init__(self, srcdir: str, builddir: str, opts: Sequence[str]) -> None:
         self.srcdir = srcdir
         self.builddir = builddir
         self.opts = [*opts]
-        self.makecmd = os.environ.get('MAKE', 'make')  # refer $MAKE to determine make command
 
     def builddir_join(self, *comps: str) -> str:
         return path.join(self.builddir, *comps)
@@ -105,10 +104,11 @@ def build_latexpdf(self) -> int:
         if self.run_generic_build('latex') > 0:
             return 1
 
-        if sys.platform == 'win32':
-            makecmd = os.environ.get('MAKE', 'make.bat')
-        else:
-            makecmd = self.makecmd
+        # Use $MAKE to determine the make command
+        make_fallback = 'make.bat' if sys.platform == 'win32' else 'make'
+        makecmd = os.environ.get('MAKE', make_fallback)
+        if not makecmd.lower().startswith('make'):
+            raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
             with chdir(self.builddir_join('latex')):
                 return subprocess.call([makecmd, 'all-pdf'])
@@ -120,10 +120,11 @@ def build_latexpdfja(self) -> int:
         if self.run_generic_build('latex') > 0:
             return 1
 
-        if sys.platform == 'win32':
-            makecmd = os.environ.get('MAKE', 'make.bat')
-        else:
-            makecmd = self.makecmd
+        # Use $MAKE to determine the make command
+        make_fallback = 'make.bat' if sys.platform == 'win32' else 'make'
+        makecmd = os.environ.get('MAKE', make_fallback)
+        if not makecmd.lower().startswith('make'):
+            raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
             with chdir(self.builddir_join('latex')):
                 return subprocess.call([makecmd, 'all-pdf'])
@@ -134,11 +135,16 @@ def build_latexpdfja(self) -> int:
     def build_info(self) -> int:
         if self.run_generic_build('texinfo') > 0:
             return 1
+
+        # Use $MAKE to determine the make command
+        makecmd = os.environ.get('MAKE', 'make')
+        if not makecmd.lower().startswith('make'):
+            raise RuntimeError('Invalid $MAKE command: %r' % makecmd)
         try:
             with chdir(self.builddir_join('texinfo')):
-                return subprocess.call([self.makecmd, 'info'])
+                return subprocess.call([makecmd, 'info'])
         except OSError:
-            print('Error: Failed to run: %s' % self.makecmd)
+            print('Error: Failed to run: %s' % makecmd)
             return 1
 
     def build_gettext(self) -> int:
diff --git a/sphinx/ext/autodoc/importer.py b/sphinx/ext/autodoc/importer.py
@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import contextlib
 import importlib
+import os
 import sys
 import traceback
 import typing
@@ -21,6 +23,8 @@
 )
 
 if TYPE_CHECKING:
+    from types import ModuleType
+
     from sphinx.ext.autodoc import ObjectMember
 
 logger = logging.getLogger(__name__)
@@ -69,6 +73,19 @@ def import_module(modname: str, warningiserror: bool = False) -> Any:
         raise ImportError(exc, traceback.format_exc()) from exc
 
 
+def _reload_module(module: ModuleType, warningiserror: bool = False) -> Any:
+    """
+    Call importlib.reload(module), convert exceptions to ImportError
+    """
+    try:
+        with logging.skip_warningiserror(not warningiserror):
+            return importlib.reload(module)
+    except BaseException as exc:
+        # Importing modules may cause any side effects, including
+        # SystemExit, so we need to catch all errors.
+        raise ImportError(exc, traceback.format_exc()) from exc
+
+
 def import_object(modname: str, objpath: list[str], objtype: str = '',
                   attrgetter: Callable[[Any, str], Any] = safe_getattr,
                   warningiserror: bool = False) -> Any:
@@ -83,23 +100,20 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
         objpath = list(objpath)
         while module is None:
             try:
-                orig_modules = frozenset(sys.modules)
-                try:
-                    # try importing with ``typing.TYPE_CHECKING == True``
-                    typing.TYPE_CHECKING = True
-                    module = import_module(modname, warningiserror=warningiserror)
-                except ImportError:
-                    # if that fails (e.g. circular import), retry with
-                    # ``typing.TYPE_CHECKING == False`` after reverting
-                    # changes made to ``sys.modules`` by the failed try
-                    for m in [m for m in sys.modules if m not in orig_modules]:
-                        sys.modules.pop(m)
-
-                    typing.TYPE_CHECKING = False
-                    module = import_module(modname, warningiserror=warningiserror)
-                finally:
-                    # ensure ``typing.TYPE_CHECKING == False``
-                    typing.TYPE_CHECKING = False
+                original_module_names = frozenset(sys.modules)
+                module = import_module(modname, warningiserror=warningiserror)
+                if os.environ.get('SPHINX_AUTODOC_RELOAD_MODULES'):
+                    new_modules = [m for m in sys.modules if m not in original_module_names]
+                    # Try reloading modules with ``typing.TYPE_CHECKING == True``.
+                    try:
+                        typing.TYPE_CHECKING = True
+                        # Ignore failures; we've already successfully loaded these modules
+                        with contextlib.suppress(ImportError, KeyError):
+                            for m in new_modules:
+                                _reload_module(sys.modules[m])
+                    finally:
+                        typing.TYPE_CHECKING = False
+                    module = sys.modules[modname]
                 logger.debug('[autodoc] import %s => %r', modname, module)
             except ImportError as exc:
                 logger.debug('[autodoc] import %s => failed', modname)
diff --git a/sphinx/search/__init__.py b/sphinx/search/__init__.py
@@ -162,7 +162,7 @@ class _JavaScriptIndex:
     SUFFIX = ')'
 
     def dumps(self, data: Any) -> str:
-        return self.PREFIX + json.dumps(data) + self.SUFFIX
+        return self.PREFIX + json.dumps(data, sort_keys=True) + self.SUFFIX
 
     def loads(self, s: str) -> Any:
         data = s[len(self.PREFIX):-len(self.SUFFIX)]
diff --git a/sphinx/theming.py b/sphinx/theming.py
@@ -69,7 +69,10 @@ def __init__(self, name: str, theme_path: str, factory: HTMLThemeFactory) -> Non
             extract_zip(theme_path, self.themedir)
 
         self.config = configparser.RawConfigParser()
-        self.config.read(path.join(self.themedir, THEMECONF), encoding='utf-8')
+        config_file_path = path.join(self.themedir, THEMECONF)
+        if not os.path.isfile(config_file_path):
+            raise ThemeError(__('theme configuration file %r not found') % config_file_path)
+        self.config.read(config_file_path, encoding='utf-8')
 
         try:
             inherit = self.config.get('theme', 'inherit')
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -1,3 +1,4 @@
+import os
 from pathlib import Path
 
 import docutils
@@ -24,6 +25,8 @@ def _init_console(locale_dir=sphinx.locale._LOCALE_DIR, catalog='sphinx'):
 # Exclude 'roots' dirs for pytest test collector
 collect_ignore = ['roots']
 
+os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
+
 
 @pytest.fixture(scope='session')
 def rootdir():
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
@@ -2103,9 +2103,8 @@ def test_singledispatchmethod_automethod(app):
     ]
 
 
-@pytest.mark.skipif(sys.version_info[:2] >= (3, 11),
-                    reason=('cython does not support python-3.11 yet. '
-                            'see https://github.com/cython/cython/issues/4365'))
+@pytest.mark.skipif(sys.version_info[:2] >= (3, 13),
+                    reason='Cython does not support Python 3.13 yet.')
 @pytest.mark.skipif(pyximport is None, reason='cython is not installed')
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_cython(app):
diff --git a/tests/test_search.py b/tests/test_search.py
diff --git a/tests/test_theming.py b/tests/test_theming.py
diff --git a/utils/CHANGES_template.rst b/utils/CHANGES_template.rst
diff --git a/utils/bump_version.py b/utils/bump_version.py
diff --git a/utils/release-checklist.rst b/utils/release-checklist.rst

Original file line number	Diff line number	Diff line change
`@@ -19,4 +19,4 @@ Changelog`
`19`	`19`	`\makeatother`
`20`	`20`
`21`	`21`
`22`		`-.. include:: ../CHANGES`
	`22`	`+.. include:: ../CHANGES.rst`