From 6c5c66bbb19cb2dcfdc25da97d4d839eec139db7 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Wed, 22 Dec 2021 18:13:19 +0000 Subject: [PATCH 1/9] Replace pkg_resources with importlib.metadata --- setup.py | 3 +-- sphinx/registry.py | 13 ++++++++----- sphinx/theming.py | 13 ++++++++----- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/setup.py b/setup.py index 8245aacefac..31089da18cd 100644 --- a/setup.py +++ b/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.920', 'docutils-stubs', "types-typed-ast", - "types-pkg_resources", "types-requests", ], 'test': [ diff --git a/sphinx/registry.py b/sphinx/registry.py index 543e5802bb2..cc2db06e598 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -21,7 +21,10 @@ from docutils.parsers import Parser from docutils.parsers.rst import Directive from docutils.transforms import Transform -from pkg_resources import iter_entry_points +try: + from importlib_metadata import entry_points +except ImportError: + from importlib.metadata import entry_points from sphinx.builders import Builder from sphinx.config import Config @@ -143,14 +146,14 @@ def preload_builder(self, app: "Sphinx", name: str) -> None: return if name not in self.builders: - entry_points = iter_entry_points('sphinx.builders', name) + builder_eps = entry_points(group='sphinx.builders') try: - entry_point = next(entry_points) - except StopIteration as exc: + entry_point = builder_eps[name] + except KeyError as exc: raise SphinxError(__('Builder name %s not registered or available' ' through entry point') % name) from exc - self.load_extension(app, entry_point.module_name) + self.load_extension(app, entry_point.module) def create_builder(self, app: "Sphinx", name: str) -> Builder: if name not in self.builders: diff --git a/sphinx/theming.py b/sphinx/theming.py index f5004022d5e..763a657fb86 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -16,7 +16,10 @@ from typing import TYPE_CHECKING, Any, Dict, List from zipfile import ZipFile -import pkg_resources +try: # Python < 3.10 (backport) + from importlib_metadata import entry_points +except ImportError: + from importlib.metadata import entry_points from sphinx import package_dir from sphinx.errors import ThemeError @@ -201,12 +204,12 @@ def load_external_theme(self, name: str) -> None: Sphinx refers to ``sphinx_themes`` entry_points. """ # look up for new styled entry_points at first - entry_points = pkg_resources.iter_entry_points('sphinx.html_themes', name) + theme_eps = entry_points(group='sphinx.html_themes') try: - entry_point = next(entry_points) - self.app.registry.load_extension(self.app, entry_point.module_name) + entry_point = theme_eps[name] + self.app.registry.load_extension(self.app, entry_point.module) return - except StopIteration: + except KeyError: pass def find_themes(self, theme_path: str) -> Dict[str, str]: From e257533ea7c9ba15283e1c03bafe56371a56dffc Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Wed, 22 Dec 2021 18:18:22 +0000 Subject: [PATCH 2/9] Add comment about import options --- sphinx/registry.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/registry.py b/sphinx/registry.py index cc2db06e598..f6dc2771fbb 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -21,7 +21,7 @@ from docutils.parsers import Parser from docutils.parsers.rst import Directive from docutils.transforms import Transform -try: +try: # Python < 3.10 (backport) from importlib_metadata import entry_points except ImportError: from importlib.metadata import entry_points From 71b3e2c822143e1f9657bbd2c3c52180cdc851b4 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Wed, 22 Dec 2021 18:27:13 +0000 Subject: [PATCH 3/9] Run isort --- sphinx/registry.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/registry.py b/sphinx/registry.py index f6dc2771fbb..c8c6b8b5a5e 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -21,6 +21,7 @@ from docutils.parsers import Parser from docutils.parsers.rst import Directive from docutils.transforms import Transform + try: # Python < 3.10 (backport) from importlib_metadata import entry_points except ImportError: From a87153c018758a49b7dd601545c044576564652c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 24 Dec 2021 10:14:19 +0900 Subject: [PATCH 4/9] autodoc: Rename autodoc_unqualified_typehints to autodoc_typehints_format (refs: #9931) --- CHANGES | 2 +- doc/usage/extensions/autodoc.rst | 11 ++++++++--- sphinx/ext/autodoc/__init__.py | 15 ++++++++------- tests/test_ext_autodoc_configs.py | 4 ++-- 4 files changed, 19 insertions(+), 13 deletions(-) diff --git a/CHANGES b/CHANGES index 77a901e853c..653223e0b22 100644 --- a/CHANGES +++ b/CHANGES @@ -13,7 +13,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 diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index d775ddee8e8..dfb08e688e7 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/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 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 5ada06a6a50..21e0a11cfe2 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1295,7 +1295,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: @@ -1325,7 +1325,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 = [] @@ -1566,7 +1566,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: @@ -1589,7 +1589,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() @@ -2120,7 +2120,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: @@ -2172,7 +2172,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 = [] @@ -2848,7 +2848,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') diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py index f3bcd6a97a1..3159e8a8ff9 100644 --- a/tests/test_ext_autodoc_configs.py +++ b/tests/test_ext_autodoc_configs.py @@ -1143,8 +1143,8 @@ def test_autodoc_typehints_description_and_type_aliases(app): @pytest.mark.sphinx('html', testroot='ext-autodoc', - confoverrides={'autodoc_unqualified_typehints': True}) -def test_autodoc_unqualified_typehints(app): + confoverrides={'autodoc_typehints_format': "short"}) +def test_autodoc_typehints_format_short(app): if sys.version_info < (3, 7): Any = 'Any' else: From c7e34936ffb197988b6dfd74227cb73bad05b345 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Fri, 24 Dec 2021 18:13:17 +0000 Subject: [PATCH 5/9] Rename variables for clarity --- sphinx/registry.py | 4 ++-- sphinx/theming.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx/registry.py b/sphinx/registry.py index c8c6b8b5a5e..3d70f8d9f02 100644 --- a/sphinx/registry.py +++ b/sphinx/registry.py @@ -147,9 +147,9 @@ def preload_builder(self, app: "Sphinx", name: str) -> None: return if name not in self.builders: - builder_eps = entry_points(group='sphinx.builders') + builder_entry_points = entry_points(group='sphinx.builders') try: - entry_point = builder_eps[name] + entry_point = builder_entry_points[name] except KeyError as exc: raise SphinxError(__('Builder name %s not registered or available' ' through entry point') % name) from exc diff --git a/sphinx/theming.py b/sphinx/theming.py index 763a657fb86..7a002201a0c 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -204,9 +204,9 @@ def load_external_theme(self, name: str) -> None: Sphinx refers to ``sphinx_themes`` entry_points. """ # look up for new styled entry_points at first - theme_eps = entry_points(group='sphinx.html_themes') + theme_entry_points = entry_points(group='sphinx.html_themes') try: - entry_point = theme_eps[name] + entry_point = theme_entry_points[name] self.app.registry.load_extension(self.app, entry_point.module) return except KeyError: From 4f9b4c2124680e99ab52e2251d0f28553efd8cb4 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 25 Dec 2021 12:54:43 +0900 Subject: [PATCH 6/9] Update CHANGES for PR #10007 --- CHANGES | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES b/CHANGES index 77a901e853c..4f46de25540 100644 --- a/CHANGES +++ b/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 -------------------- From e8b3c9cf186dbd5d8aacb88adaadd81fbccb9be4 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 25 Dec 2021 18:42:36 +0900 Subject: [PATCH 7/9] refactor: docs: Use :param: fields for add_js_file() and add_css_file() --- sphinx/application.py | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 475f08853e8..a26c3d659eb 100644 --- a/sphinx/application.py +++ b/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 - ``