Merge branch '4.x'

CHANGES

@@ -83,6 +83,8 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #10112: extlinks: Disable hardcoded links detector by default
+
 Deprecated
 ----------
 
@@ -94,6 +96,8 @@ Features added
 * #10260: Enable ``FORCE_COLOR`` and ``NO_COLOR`` for terminal colouring
 * #10234: autosummary: Add "autosummary" CSS class to summary tables
 * #10125: extlinks: Improve suggestion message for a reference having title
+* #10112: extlinks: Add :confval:`extlinks_detect_hardcoded_links` to enable
+  hardcoded links detector feature
 * #9494, #9456: html search: Add a config variable
   :confval:`html_show_search_summary` to enable/disable the search summaries
 * #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:'/' as
@@ -110,6 +114,7 @@ Bugs fixed
   ``no-value`` option
 * #9971: autodoc: TypeError is raised when the target object is annotated by
   unhashable object
+* #10277: html search: Could not search short words (ex. "use")
 * #9529: LaTeX: named auto numbered footnote (ex. ``[#named]``) that is referred
   multiple times was rendered to a question mark
 * #9924: LaTeX: multi-line :rst:dir:`cpp:function` directive has big vertical
@@ -118,6 +123,9 @@ Bugs fixed
   variables/structure members 
 * #10175: LaTeX: named footnote reference is linked to an incorrect footnote if
   the name is also used in the different document
+* #10269: manpage: Failed to resolve the title of :ref: cross references
+* #10179: i18n: suppress "rST localization" warning
+* #10118: imgconverter: Unnecessary availablity check is called for remote URIs
 * #10181: napoleon: attributes are displayed like class attributes for google
   style docstrings when :confval:`napoleon_use_ivar` is enabled
 * #10122: sphinx-build: make.bat does not check the installation of sphinx-build

doc/conf.py

@@ -109,7 +109,7 @@
 
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
-    'requests': ('https://requests.readthedocs.io/en/master', None),
+    'requests': ('https://docs.python-requests.org/en/latest/', None),
     'readthedocs': ('https://docs.readthedocs.io/en/stable', None),
 }
 

doc/extdev/parserapi.rst

@@ -35,3 +35,4 @@ to configure their settings appropriately.
 .. module:: sphinx.parsers
 
 .. autoclass:: Parser
+   :members:

doc/tutorial/automatic-doc-generation.rst

@@ -4,10 +4,9 @@ Automatic documentation generation from code
 In the :ref:`previous section <tutorial-describing-objects>` of the tutorial
 you manually documented a Python function in Sphinx. However, the description
 was out of sync with the code itself, since the function signature was not
-the same. Besides, it would be nice to reuse `Python
-docstrings <https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring>`_
-in the documentation, rather than having to write the information in two
-places.
+the same. Besides, it would be nice to reuse :pep:`Python docstrings
+<257#what-is-a-docstring>` in the documentation, rather than having to write
+the information in two places.
 
 Fortunately, :doc:`the autodoc extension </usage/extensions/autodoc>` provides this
 functionality.

doc/usage/extensions/autodoc.rst

@@ -634,8 +634,8 @@ There are also config values that you can set:
    full-qualified object name.  It is used to keep type aliases not evaluated in
    the document.  Defaults to empty (``{}``).
 
-   The type aliases are only available if your program enables `Postponed
-   Evaluation of Annotations (PEP 563)`__ feature via ``from __future__ import
+   The type aliases are only available if your program enables :pep:`Postponed
+   Evaluation of Annotations (PEP 563) <563>` feature via ``from __future__ import
    annotations``.
 
    For example, there is code using a type alias::
@@ -662,7 +662,6 @@ There are also config values that you can set:
 
         ...
 
-   .. __: https://www.python.org/dev/peps/pep-0563/
    .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
    .. versionadded:: 3.3
 

doc/usage/extensions/doctest.rst

@@ -93,8 +93,8 @@ a comma-separated list of group names.
      * ``<``, ``>``: Exclusive ordered comparison clause
      * ``===``: Arbitrary equality clause.
 
-     ``pyversion`` option is followed `PEP-440: Version Specifiers
-     <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`__.
+     ``pyversion`` option is followed :pep:`PEP-440: Version Specifiers
+     <440#version-specifiers>`.
 
      .. versionadded:: 1.6
 

doc/usage/extensions/example_google.py

@@ -45,7 +45,7 @@
 def function_with_types_in_docstring(param1, param2):
     """Example function with types documented in the docstring.
 
-    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    :pep:`484` type annotations are supported. If attribute, parameter, and
     return types are annotated according to `PEP 484`_, they do not need to be
     included in the docstring:
 
@@ -55,10 +55,6 @@ def function_with_types_in_docstring(param1, param2):
 
     Returns:
         bool: The return value. True for success, False otherwise.
-
-    .. _PEP 484:
-        https://www.python.org/dev/peps/pep-0484/
-
     """
 
 
@@ -311,4 +307,4 @@ class ExamplePEP526Class:
     """
 
     attr1: str
-    attr2: int
+    attr2: int

doc/usage/extensions/example_numpy.py

@@ -55,7 +55,7 @@
 def function_with_types_in_docstring(param1, param2):
     """Example function with types documented in the docstring.
 
-    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    :pep:`484` type annotations are supported. If attribute, parameter, and
     return types are annotated according to `PEP 484`_, they do not need to be
     included in the docstring:
 
@@ -70,10 +70,6 @@ def function_with_types_in_docstring(param1, param2):
     -------
     bool
         True if successful, False otherwise.
-
-    .. _PEP 484:
-        https://www.python.org/dev/peps/pep-0484/
-
     """
 
 

doc/usage/extensions/extlinks.rst

@@ -59,3 +59,11 @@ The extension adds a config value:
 
    Since links are generated from the role in the reading stage, they appear as
    ordinary links to e.g. the ``linkcheck`` builder.
+
+.. confval:: extlinks_detect_hardcoded_links
+
+   If enabled, extlinks emits a warning if a hardcoded link is replaceable
+   by an extlink, and suggests a replacement via warning.  It defaults to
+   ``False``.
+
+   .. versionadded:: 4.5

doc/usage/extensions/napoleon.rst

@@ -26,7 +26,7 @@ Are you tired of writing docstrings that look like this::
     :rtype: BufferedFileStorage
 
 `reStructuredText`_ is great, but it creates visually dense, hard to read
-`docstrings`_. Compare the jumble above to the same thing rewritten
+:pep:`docstrings <287>`. Compare the jumble above to the same thing rewritten
 according to the `Google Python Style Guide`_::
 
     Args:
@@ -50,7 +50,6 @@ the documentation, so it doesn't modify any of the docstrings in your actual
 source code files.
 
 .. _ReStructuredText: https://docutils.sourceforge.io/rst.html
-.. _docstrings: https://www.python.org/dev/peps/pep-0287/
 .. _Google Python Style Guide:
    https://google.github.io/styleguide/pyguide.html
 .. _Google:
@@ -199,11 +198,11 @@ not be mixed. Choose one style for your project and be consistent with it.
 Type Annotations
 ~~~~~~~~~~~~~~~~
 
-`PEP 484`_ introduced a standard way to express types in Python code.
+:pep:`484` introduced a standard way to express types in Python code.
 This is an alternative to expressing types directly in docstrings.
-One benefit of expressing types according to `PEP 484`_ is that
+One benefit of expressing types according to :pep:`484` is that
 type checkers and IDEs can take advantage of them for static code
-analysis. `PEP 484`_ was then extended by `PEP 526`_ which introduced
+analysis. :pep:`484` was then extended by :pep:`526` which introduced
 a similar way to annotate variables (and attributes).
 
 Google style with Python 3 type annotations::
@@ -267,9 +266,7 @@ Google style with types in docstrings::
    `Python 2/3 compatible annotations`_ aren't currently
    supported by Sphinx and won't show up in the docs.
 
-.. _PEP 484: https://www.python.org/dev/peps/pep-0484/
-.. _PEP 526: https://www.python.org/dev/peps/pep-0526/
-.. _Python 2/3 compatible annotations: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+.. _Python 2/3 compatible annotations: https://peps.python.org/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 
 
 Configuration
@@ -548,7 +545,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 
 .. confval:: napoleon_attr_annotations
 
-   True to allow using `PEP 526`_ attributes annotations in classes.
+   True to allow using :pep:`526` attributes annotations in classes.
    If an attribute is documented in the docstring without a type and
    has an annotation in the class body, that type is used.
 

setup.cfg

@@ -1,5 +1,5 @@
 [metadata]
-license_file = LICENSE
+license_files = LICENSE
 
 [egg_info]
 tag_build = .dev

sphinx/builders/manpage.py

@@ -10,7 +10,6 @@
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.errors import NoUri
 from sphinx.locale import __
 from sphinx.util import logging, progress_message
 from sphinx.util.console import darkgreen  # type: ignore
@@ -41,9 +40,7 @@ def get_outdated_docs(self) -> Union[str, List[str]]:
         return 'all manpages'  # for now
 
     def get_target_uri(self, docname: str, typ: str = None) -> str:
-        if typ == 'token':
-            return ''
-        raise NoUri(docname, typ)
+        return ''
 
     @progress_message(__('writing'))
     def write(self, *ignored: Any) -> None:

sphinx/ext/autodoc/__init__.py

@@ -1661,7 +1661,7 @@ def add_directive_header(self, sig: str) -> None:
         if not self.doc_as_attr and self.options.show_inheritance:
             if inspect.getorigbases(self.object):
                 # A subclass of generic types
-                # refs: PEP-560 <https://www.python.org/dev/peps/pep-0560/>
+                # refs: PEP-560 <https://peps.python.org/pep-0560/>
                 bases = list(self.object.__orig_bases__)
             elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
                 # A normal class

sphinx/ext/doctest.py

@@ -41,7 +41,7 @@ def is_allowed_version(spec: str, version: str) -> bool:
     """Check `spec` satisfies `version` or not.
 
     This obeys PEP-440 specifiers:
-    https://www.python.org/dev/peps/pep-0440/#version-specifiers
+    https://peps.python.org/pep-0440/#version-specifiers
 
     Some examples:
 

sphinx/ext/extlinks.py

@@ -45,6 +45,9 @@ class ExternalLinksChecker(SphinxPostTransform):
     default_priority = 500
 
     def run(self, **kwargs: Any) -> None:
+        if not self.config.extlinks_detect_hardcoded_links:
+            return
+
         for refnode in self.document.findall(nodes.reference):
             self.check_uri(refnode)
 
@@ -119,6 +122,8 @@ def setup_link_roles(app: Sphinx) -> None:
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('extlinks', {}, 'env')
+    app.add_config_value('extlinks_detect_hardcoded_links', False, 'env')
+
     app.connect('builder-inited', setup_link_roles)
     app.add_post_transform(ExternalLinksChecker)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}