Repository: sphinx-doc/sphinx

Issue:
Add `autodecorator` to autodoc extension
Since issue #478 was completed there has been talk about the possibility of adding `autodecorator` and possibly `autodecoratormethod` to the autodoc extension.  Any chance that could be added?

I'm not that familiar with how the underlying sphinx code works but I was able to get the `autodecorator` to work well enough for me just by doing this:

```
class DecoratorDocumenter(FunctionDocumenter):
    """
    Specialized Documenter subclass for decorator functions.
    """
    objtype = 'decorator'
```

and then adding the autodocumenter in the `setup()` at the end of the file?  Is that all that needs to be done?

---
- Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1148
- Originally reported by: Anonymous
- Originally created at: 2013-04-15T20:12:55.391


Discussion:

Patch:
diff --git a/CHANGES b/CHANGES
index fd40e17dc..49c8b667f 100644
--- a/CHANGES
+++ b/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
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 45789e0a2..cb41cb07d 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/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::
 
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 9e65e595d..f76faf322 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1032,6 +1032,23 @@ def document_members(self, all_members=False):
         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)


Test patch:
diff --git a/tests/roots/test-ext-autodoc/target/decorator.py b/tests/roots/test-ext-autodoc/target/decorator.py
new file mode 100644
index 000000000..4ccfedf28
--- /dev/null
+++ b/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
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 7758f442d..943ba5a7a 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -602,6 +602,29 @@ def assert_result_contains(item, objtype, name, **kw):
                            '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')