From 686486498c228cc83fdd37a42861d9fac145d33e Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Fri, 15 Feb 2019 01:58:09 +0900
Subject: [PATCH] Closes #1148: autodoc: Add autodecorator directive for
 decorators

---
 CHANGES                                       |  1 +
 doc/usage/extensions/autodoc.rst              |  4 +++-
 sphinx/ext/autodoc/__init__.py                | 18 +++++++++++++++
 .../test-ext-autodoc/target/decorator.py      | 16 +++++++++++++
 tests/test_autodoc.py                         | 23 +++++++++++++++++++
 5 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 tests/roots/test-ext-autodoc/target/decorator.py

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 @@ 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)
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 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')