From 6af38961036dbf05d9ff3c99ab8d39e8b2b5ec2a Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Sat, 13 Apr 2019 20:25:07 +0900
Subject: [PATCH] Add PyFunction and PyVariable; directives for python
 functions and variables

---
 CHANGES                   |  1 +
 doc/extdev/deprecated.rst | 10 +++++++++-
 sphinx/domains/python.py  | 39 +++++++++++++++++++++++++++++++++++++--
 tests/test_domain_py.py   | 23 +++++++++++++++++++++++
 4 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index a36988937..ce7ed83c2 100644
--- a/CHANGES
+++ b/CHANGES
@@ -34,6 +34,7 @@ Deprecated
 * ``sphinx.directives.TocTree``
 * ``sphinx.directives.VersionChange``
 * ``sphinx.domains.python.PyClassmember``
+* ``sphinx.domains.python.PyModulelevel``
 * ``sphinx.domains.std.StandardDomain._resolve_citation_xref()``
 * ``sphinx.domains.std.StandardDomain.note_citations()``
 * ``sphinx.domains.std.StandardDomain.note_citation_refs()``
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index ffe0bdccb..97eb0689a 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -121,9 +121,17 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``sphinx.domains.python.PyAttribute``,
        ``sphinx.domains.python.PyMethod``,
-       ``sphinx.domains.python.PyClassMethod`` and
+       ``sphinx.domains.python.PyClassMethod``,
+       ``sphinx.domains.python.PyObject`` and
        ``sphinx.domains.python.PyStaticMethod``
 
+   * - ``sphinx.domains.python.PyModulelevel``
+     - 2.1
+     - 4.0
+     - ``sphinx.domains.python.PyFunction``,
+       ``sphinx.domains.python.PyObject`` and
+       ``sphinx.domains.python.PyVariable``
+
    * - ``sphinx.domains.std.StandardDomain._resolve_citation_xref()``
      - 2.1
      - 4.0
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index de31eef00..898265f0b 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -410,6 +410,13 @@ class PyModulelevel(PyObject):
     Description of an object on module level (functions, data).
     """
 
+    def run(self):
+        # type: () -> List[nodes.Node]
+        warnings.warn('PyClassmember is deprecated.',
+                      RemovedInSphinx40Warning)
+
+        return super().run()
+
     def needs_arglist(self):
         # type: () -> bool
         return self.objtype == 'function'
@@ -428,6 +435,34 @@ class PyModulelevel(PyObject):
             return ''
 
 
+class PyFunction(PyObject):
+    """Description of a function."""
+
+    def needs_arglist(self):
+        # type: () -> bool
+        return True
+
+    def get_index_text(self, modname, name_cls):
+        # type: (str, Tuple[str, str]) -> str
+        name, cls = name_cls
+        if modname:
+            return _('%s() (in module %s)') % (name, modname)
+        else:
+            return _('%s() (built-in function)') % name
+
+
+class PyVariable(PyObject):
+    """Description of a variable."""
+
+    def get_index_text(self, modname, name_cls):
+        # type: (str, Tuple[str, str]) -> str
+        name, cls = name_cls
+        if modname:
+            return _('%s (in module %s)') % (name, modname)
+        else:
+            return _('%s (built-in variable)') % name
+
+
 class PyClasslike(PyObject):
     """
     Description of a class-like object (classes, interfaces, exceptions).
@@ -839,8 +874,8 @@ class PythonDomain(Domain):
     }  # type: Dict[str, ObjType]
 
     directives = {
-        'function':        PyModulelevel,
-        'data':            PyModulelevel,
+        'function':        PyFunction,
+        'data':            PyVariable,
         'class':           PyClasslike,
         'exception':       PyClasslike,
         'method':          PyMethod,
diff --git a/tests/test_domain_py.py b/tests/test_domain_py.py
index afc34a697..e7ff407bd 100644
--- a/tests/test_domain_py.py
+++ b/tests/test_domain_py.py
@@ -292,6 +292,29 @@ def test_pyobject_prefix(app):
     assert doctree[1][1][3].astext().strip() == 'FooBar.say'    # not stripped
 
 
+def test_pydata(app):
+    text = ".. py:data:: var\n"
+    domain = app.env.get_domain('py')
+    doctree = restructuredtext.parse(app, text)
+    assert_node(doctree, (addnodes.index,
+                          [desc, ([desc_signature, desc_name, "var"],
+                                  [desc_content, ()])]))
+    assert 'var' in domain.objects
+    assert domain.objects['var'] == ('index', 'data')
+
+
+def test_pyfunction(app):
+    text = ".. py:function:: func\n"
+    domain = app.env.get_domain('py')
+    doctree = restructuredtext.parse(app, text)
+    assert_node(doctree, (addnodes.index,
+                          [desc, ([desc_signature, ([desc_name, "func"],
+                                                    [desc_parameterlist, ()])],
+                                  [desc_content, ()])]))
+    assert 'func' in domain.objects
+    assert domain.objects['func'] == ('index', 'function')
+
+
 def test_pymethod(app):
     text = (".. py:class:: Class\n"
             "\n"