From 74a5f350a19e9a54ef53c653c95d7741f3de4e0e Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 13 Jan 2020 13:16:59 +0900 Subject: [PATCH] Add new event: autodoc-before-process-signature --- CHANGES | 1 + doc/usage/extensions/autodoc.rst | 11 +++++++++++ sphinx/ext/autodoc/__init__.py | 11 +++++++++++ 3 files changed, 23 insertions(+) diff --git a/CHANGES b/CHANGES index 9a481b588..f6f1d44fd 100644 --- a/CHANGES +++ b/CHANGES @@ -35,6 +35,7 @@ Features added images (imagesize-1.2.0 or above is required) * #6994: imgconverter: Support illustrator file (.ai) to .png conversion * autodoc: Support Positional-Only Argument separator (PEP-570 compliant) +* #2755: autodoc: Add new event: :event:`autodoc-before-process-signature` * SphinxTranslator now calls visitor/departure method for super node class if visitor/departure method for original node class not found diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 3bb9630bd..4a7ea3f3c 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -494,6 +494,17 @@ autodoc provides the following additional events: auto directive :param lines: the lines of the docstring, see above +.. event:: autodoc-before-process-signature (app, obj, bound_method) + + .. versionadded:: 2.4 + + Emitted before autodoc formats a signature for an object. The event handler + can modify an object to change its signature. + + :param app: the Sphinx application object + :param obj: the object itself + :param bound_method: a boolean indicates an object is bound method or not + .. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation) .. versionadded:: 0.5 diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 2124b2d25..1dc2d0f69 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -983,8 +983,11 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ not inspect.isbuiltin(self.object) and not inspect.isclass(self.object) and hasattr(self.object, '__call__')): + self.env.app.emit('autodoc-before-process-signature', + self.object.__call__, False) sig = inspect.signature(self.object.__call__) else: + self.env.app.emit('autodoc-before-process-signature', self.object, False) sig = inspect.signature(self.object) args = stringify_signature(sig, **kwargs) except TypeError: @@ -996,9 +999,13 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ # typing) we try to use the constructor signature as function # signature without the first argument. try: + self.env.app.emit('autodoc-before-process-signature', + self.object.__new__, True) sig = inspect.signature(self.object.__new__, bound_method=True) args = stringify_signature(sig, show_return_annotation=False, **kwargs) except TypeError: + self.env.app.emit('autodoc-before-process-signature', + self.object.__init__, True) sig = inspect.signature(self.object.__init__, bound_method=True) args = stringify_signature(sig, show_return_annotation=False, **kwargs) @@ -1081,6 +1088,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: not(inspect.ismethod(initmeth) or inspect.isfunction(initmeth)): return None try: + self.env.app.emit('autodoc-before-process-signature', initmeth, True) sig = inspect.signature(initmeth, bound_method=True) return stringify_signature(sig, show_return_annotation=False, **kwargs) except TypeError: @@ -1284,8 +1292,10 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: # can never get arguments of a C function or method return None if inspect.isstaticmethod(self.object, cls=self.parent, name=self.object_name): + self.env.app.emit('autodoc-before-process-signature', self.object, False) sig = inspect.signature(self.object, bound_method=False) else: + self.env.app.emit('autodoc-before-process-signature', self.object, True) sig = inspect.signature(self.object, bound_method=True) args = stringify_signature(sig, **kwargs) @@ -1558,6 +1568,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value('autodoc_typehints', "signature", True, ENUM("signature", "none")) app.add_config_value('autodoc_warningiserror', True, True) app.add_config_value('autodoc_inherit_docstrings', True, True) + app.add_event('autodoc-before-process-signature') app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member')