Merge pull request #6292 from tk0miya/refactor_py_domain5

Add PyFunction and PyVariable; directives for python functions and variables

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()``

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

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,
+        'function':        PyFunction,
-        'data':            PyModulelevel,
+        'data':            PyVariable,
         'class':           PyClasslike,
         'exception':       PyClasslike,
         'method':          PyMethod,

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"