Merge branch '4.x' into 10009_exception_on_getdoc

Author: tk0miya

CHANGES

@@ -4,6 +4,9 @@ Release 4.4.0 (in development)
 Dependencies
 ------------
 
+* #10007: Use ``importlib_metadata`` for python-3.9 or older
+* #10007: Drop ``setuptools``
+
 Incompatible changes
 --------------------
 
@@ -13,7 +16,7 @@ Deprecated
 Features added
 --------------
 
-* #9075: autodoc: Add a config variable :confval:`autodoc_unqualified_typehints`
+* #9075: autodoc: Add a config variable :confval:`autodoc_typehints_format`
   to suppress the leading module names of typehints of function signatures (ex.
   ``io.StringIO`` -> ``StringIO``)
 * #9831: Autosummary now documents only the members specified in a module's
@@ -46,6 +49,7 @@ Bugs fixed
   with Python 3.10
 * #9968: autodoc: instance variables are not shown if __init__ method has
   position-only-arguments
+* #9194: autodoc: types under the "typing" module are not hyperlinked
 * #10009: autodoc: Crashes if target object raises an error on getting docstring
 * #9947: i18n: topic directive having a bullet list can't be translatable
 * #9878: mathjax: MathJax configuration is placed after loading MathJax itself

doc/usage/extensions/autodoc.rst

@@ -662,10 +662,15 @@ There are also config values that you can set:
    .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
    .. versionadded:: 3.3
 
-.. confval:: autodoc_unqualified_typehints
+.. confval:: autodoc_typehints_format
 
-   If True, the leading module names of typehints of function signatures are
-   removed (ex.  ``io.StringIO`` -> ``StringIO``).  Defaults to False.
+   This value controls the format of typehints.  The setting takes the
+   following values:
+
+   * ``'fully-qualified'`` -- Show the module name and its name of typehints
+     (default)
+   * ``'short'`` -- Suppress the leading module names of the typehints
+     (ex. ``io.StringIO`` -> ``StringIO``)
 
    .. versionadded:: 4.4
 

setup.py

@@ -29,8 +29,8 @@
     'alabaster>=0.7,<0.8',
     'imagesize',
     'requests>=2.5.0',
-    'setuptools',
     'packaging',
+    "importlib-metadata>=4.4; python_version < '3.10'",
 ]
 
 extras_require = {
@@ -47,7 +47,6 @@
         'mypy>=0.930',
         'docutils-stubs',
         "types-typed-ast",
-        "types-pkg_resources",
         "types-requests",
     ],
     'test': [

sphinx/application.py

@@ -933,14 +933,18 @@ def add_post_transform(self, transform: Type[Transform]) -> None:
     def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
         """Register a JavaScript file to include in the HTML output.
 
-        Add *filename* to the list of JavaScript files that the default HTML
-        template will include in order of *priority* (ascending).  The filename
-        must be relative to the HTML static path , or a full URI with scheme.
-        If the priority of the JavaScript file is the same as others, the JavaScript
-        files will be included in order of registration.  If the keyword
-        argument ``body`` is given, its value will be added between the
-        ``<script>`` tags. Extra keyword arguments are included as attributes of
-        the ``<script>`` tag.
+        :param filename: The filename of the JavaScript file.  It must be relative to the HTML
+                         static path, a full URI with scheme, or ``None`` value.  The ``None``
+                         value is used to create inline ``<script>`` tag.  See the description
+                         of *kwargs* below.
+        :param priority: The priority to determine the order of ``<script>`` tag for
+                         JavaScript files.  See list of "prority range for JavaScript
+                         files" below.  If the priority of the JavaScript files it the same
+                         as others, the JavaScript files will be loaded in order of
+                         registration.
+        :param kwargs: Extra keyword arguments are included as attributes of the ``<script>``
+                       tag.  A special keyword argument ``body`` is given, its value will be
+                       added between the ``<script>`` tag.
 
         Example::
 
@@ -984,12 +988,14 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None
     def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None:
         """Register a stylesheet to include in the HTML output.
 
-        Add *filename* to the list of CSS files that the default HTML template
-        will include in order of *priority* (ascending).  The filename must be
-        relative to the HTML static path, or a full URI with scheme.  If the
-        priority of the CSS file is the same as others, the CSS files will be
-        included in order of registration.  The keyword arguments are also
-        accepted for attributes of ``<link>`` tag.
+        :param filename: The filename of the CSS file.  It must be relative to the HTML
+                         static path, or a full URI with scheme.
+        :param priority: The priority to determine the order of ``<link>`` tag for the
+                         CSS files.  See list of "prority range for CSS files" below.
+                         If the priority of the CSS files it the same as others, the
+                         CSS files will be loaded in order of registration.
+        :param kwargs: Extra keyword arguments are included as attributes of the ``<link>``
+                       tag.
 
         Example::
 

sphinx/domains/python.py

@@ -83,7 +83,8 @@ class ModuleEntry(NamedTuple):
 def type_to_xref(target: str, env: BuildEnvironment = None, suppress_prefix: bool = False
                  ) -> addnodes.pending_xref:
     """Convert a type string to a cross reference node."""
-    if target == 'None':
+    if target == 'None' or target.startswith('typing.'):
+        # typing module provides non-class types.  Obj reference is good to refer them.
         reftype = 'obj'
     else:
         reftype = 'class'
@@ -104,6 +105,8 @@ def type_to_xref(target: str, env: BuildEnvironment = None, suppress_prefix: boo
         text = target.split('.')[-1]
     elif suppress_prefix:
         text = target.split('.')[-1]
+    elif target.startswith('typing.'):
+        text = target[7:]
     else:
         text = target
 
@@ -203,10 +206,16 @@ def unparse(node: ast.AST) -> List[Node]:
             return result
         else:
             if sys.version_info < (3, 8):
-                if isinstance(node, ast.Ellipsis):
+                if isinstance(node, ast.Bytes):
+                    return [addnodes.desc_sig_literal_string('', repr(node.s))]
+                elif isinstance(node, ast.Ellipsis):
                     return [addnodes.desc_sig_punctuation('', "...")]
                 elif isinstance(node, ast.NameConstant):
                     return [nodes.Text(node.value)]
+                elif isinstance(node, ast.Num):
+                    return [addnodes.desc_sig_literal_string('', repr(node.n))]
+                elif isinstance(node, ast.Str):
+                    return [addnodes.desc_sig_literal_string('', repr(node.s))]
 
             raise SyntaxError  # unsupported syntax
 
@@ -1481,7 +1490,7 @@ def istyping(s: str) -> bool:
         return None
     elif node.get('reftype') in ('class', 'obj') and node.get('reftarget') == 'None':
         return contnode
-    elif node.get('reftype') in ('class', 'exc'):
+    elif node.get('reftype') in ('class', 'obj', 'exc'):
         reftarget = node.get('reftarget')
         if inspect.isclass(getattr(builtins, reftarget, None)):
             # built-in class

sphinx/ext/autodoc/__init__.py

@@ -1297,7 +1297,7 @@ def can_document_member(cls, member: Any, membername: str, isattr: bool, parent:
     def format_args(self, **kwargs: Any) -> str:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         try:
@@ -1327,7 +1327,7 @@ def add_directive_header(self, sig: str) -> None:
             self.add_line('   :async:', sourcename)
 
     def format_signature(self, **kwargs: Any) -> str:
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         sigs = []
@@ -1568,7 +1568,7 @@ def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
     def format_args(self, **kwargs: Any) -> str:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         try:
@@ -1591,7 +1591,7 @@ def format_signature(self, **kwargs: Any) -> str:
             # do not show signatures
             return ''
 
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         sig = super().format_signature()
@@ -2122,7 +2122,7 @@ def import_object(self, raiseerror: bool = False) -> bool:
     def format_args(self, **kwargs: Any) -> str:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         try:
@@ -2174,7 +2174,7 @@ def document_members(self, all_members: bool = False) -> None:
         pass
 
     def format_signature(self, **kwargs: Any) -> str:
-        if self.config.autodoc_unqualified_typehints:
+        if self.config.autodoc_typehints_format == "short":
             kwargs.setdefault('unqualified_typehints', True)
 
         sigs = []
@@ -2850,7 +2850,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
                          ENUM('all', 'documented'))
     app.add_config_value('autodoc_type_aliases', {}, True)
-    app.add_config_value('autodoc_unqualified_typehints', False, 'env')
+    app.add_config_value('autodoc_typehints_format', "fully-qualified", 'env',
+                         ENUM("fully-qualified", "short"))
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)
     app.add_event('autodoc-before-process-signature')

sphinx/locale/.tx/config

@@ -5,4 +5,3 @@ host = https://www.transifex.com
 file_filter = <lang>/LC_MESSAGES/sphinx.po
 source_file = sphinx.pot
 source_lang = en
-