Closes #1148: autodoc: Add autodecorator directive for decorators

CHANGES

@@ -166,6 +166,7 @@ Features added
 * #5533: autodoc: :confval:`autodoc_default_options` supports ``member-order``
 * #5394: autodoc: Display readable names in type annotations for mocked objects
 * #5459: autodoc: :confval:`autodoc_default_options` accepts ``True`` as a value
+* #1148: autodoc: Add :rst:dir:`autodecorator` directive for decorators
 * #5635: autosummary: Add :confval:`autosummary_mock_imports` to mock external
   libraries on importing targets
 * #4018: htmlhelp: Add :confval:`htmlhelp_file_suffix` and

doc/usage/extensions/autodoc.rst

@@ -237,6 +237,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
 
 .. rst:directive:: autofunction
+                   autodecorator
                    autodata
                    automethod
                    autoattribute
@@ -293,10 +294,11 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
       docstrings.
    .. versionchanged:: 1.1
       Comment docs are now allowed on the same line after an assignment.
-
    .. versionchanged:: 1.2
       :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation``
       option.
+   .. versionchanged:: 2.0
+      :rst:dir:`autodecorator` added.
 
    .. note::
 

sphinx/ext/autodoc/__init__.py

@@ -1032,6 +1032,23 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
         pass
 
 
+class DecoratorDocumenter(FunctionDocumenter):
+    """
+    Specialized Documenter subclass for decorator functions.
+    """
+    objtype = 'decorator'
+
+    # must be lower than FunctionDocumenter
+    priority = -1
+
+    def format_args(self):
+        args = super().format_args()
+        if ',' in args:
+            return args
+        else:
+            return None
+
+
 class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type: ignore
     """
     Specialized Documenter subclass for classes.
@@ -1461,6 +1478,7 @@ def setup(app):
     app.add_autodocumenter(ExceptionDocumenter)
     app.add_autodocumenter(DataDocumenter)
     app.add_autodocumenter(FunctionDocumenter)
+    app.add_autodocumenter(DecoratorDocumenter)
     app.add_autodocumenter(MethodDocumenter)
     app.add_autodocumenter(AttributeDocumenter)
     app.add_autodocumenter(InstanceAttributeDocumenter)

tests/roots/test-ext-autodoc/target/decorator.py

@@ -0,0 +1,16 @@
+def deco1(func):
+    """docstring for deco1"""
+    def wrapper():
+        return func()
+
+    return wrapper
+
+
+def deco2(condition, message):
+    """docstring for deco2"""
+    def decorator(func):
+        def wrapper():
+            return func()
+
+        return wrapper
+    return decorator

tests/test_autodoc.py

@@ -602,6 +602,29 @@ def test_generate():
                            'Class.meth', more_content=add_content)
 
 
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodoc_decorator(app):
+    actual = do_autodoc(app, 'decorator', 'target.decorator.deco1')
+    assert list(actual) == [
+        '',
+        '.. py:decorator:: deco1',
+        '   :module: target.decorator',
+        '',
+        '   docstring for deco1',
+        '   '
+    ]
+
+    actual = do_autodoc(app, 'decorator', 'target.decorator.deco2')
+    assert list(actual) == [
+        '',
+        '.. py:decorator:: deco2(condition, message)',
+        '   :module: target.decorator',
+        '',
+        '   docstring for deco2',
+        '   '
+    ]
+
+
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_autodoc_exception(app):
     actual = do_autodoc(app, 'exception', 'target.CustomEx')