Implementing meta field for specifying "self" reference in documentation for special methods

Author: johnpmcconnell

README.rst

@@ -28,6 +28,7 @@ as
 self + other
     Docstring
 
+It also works when using autodoc on a class that implements these methods.
 
 After installing this module, add the following to your `conf.py` to enable it
 
@@ -38,6 +39,25 @@ After installing this module, add the following to your `conf.py` to enable it
         'sphinxcontrib.prettyspecialmethods',
     ]
 
+Changing "self"
+---------------
+
+If a `meta info field`_ named :code:`self-param` is included in the docstring, its
+value will be used in place of "self" in the output:
+
+.. _meta info field: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
+
+.. code-block:: rst
+
+    .. method:: __add__(other)
+        Docstring
+        :meta self-param: obj
+
+renders to
+
+obj + other
+    Docstring
+
 
 Links
 -----

sphinxcontrib/prettyspecialmethods.py

@@ -10,12 +10,13 @@
 
 import pbr.version
 import sphinx.addnodes as SphinxNodes
-from docutils.nodes import Text, emphasis, inline
 from sphinx.transforms import SphinxTransform
+from docutils.nodes import Text, emphasis, field, field_name, field_body, inline, pending
 
 if False:
     # For type annotations
     from typing import Any, Dict  # noqa
+    from docutils.nodes import Node  # noqa
     from sphinx.application import Sphinx  # noqa
 
 __version__ = pbr.version.VersionInfo(
@@ -186,12 +187,51 @@ def brackets(parameters_node, self_param):
 }
 
 
+class PendingSelfParamName(pending):
+    def __init__(self, name):
+        # type: (str) -> None
+        super().__init__(
+            transform=PrettifySpecialMethods,
+            details={'self_param': name},
+        )
+
+    @property
+    def name(self):
+        # type: () -> str
+        return self.details['self_param']
+
+
+def is_meta_self_param_info_field(node):
+    # type: (Node) -> bool
+    if not isinstance(node, field):
+        return False
+
+    name = node.next_node(field_name).astext()
+    return name == 'meta self-param'
+
+
+def convert_meta_self_param(app, domain, objtype, contentnode):
+    # type: (Sphinx, str, str, Node) -> None
+    if not domain == 'py' or 'method' not in objtype:
+        return
+
+    # Note: Using next_node means we only find the first instance
+    # of selfparam. Additional selfparam fields are ignored and eventually
+    # deleted by the Python domain's meta filter.
+    selfparam_field = contentnode.next_node(is_meta_self_param_info_field)
+
+    if selfparam_field:
+        selfparam: str = selfparam_field.next_node(field_body).astext()
+        contentnode.append(PendingSelfParamName(selfparam))
+        selfparam_field.replace_self(())
+
+
 class PrettifySpecialMethods(SphinxTransform):
     default_priority = 800
 
     def apply(self):
         methods = (
-            sig for sig in self.document.traverse(SphinxNodes.desc_signature)
+            sig.parent for sig in self.document.traverse(SphinxNodes.desc_signature)
             if 'class' in sig
         )
 
@@ -200,11 +240,22 @@ def apply(self):
             method_name = name_node.astext()
 
             if method_name in SPECIAL_METHODS:
+                # Determine name to use for self in new specification
+                # using first child occurence
+                pending_self_param = ref.next_node(PendingSelfParamName)
+                self_param = pending_self_param.name if pending_self_param else 'self'
+
                 parameters_node = ref.next_node(SphinxNodes.desc_parameterlist)
 
-                name_node.replace_self(SPECIAL_METHODS[method_name](name_node, parameters_node, 'self'))
+                new_sig = SPECIAL_METHODS[method_name](name_node, parameters_node, self_param)
+
+                name_node.replace_self(new_sig)
                 parameters_node.replace_self(())
 
+        # Remove ALL occurrences of PendingSelfParamName
+        for p in self.document.traverse(PendingSelfParamName):
+            p.replace_self(())
+
 
 def show_special_methods(app, what, name, obj, skip, options):
     if what == 'class' and name in SPECIAL_METHODS and getattr(obj, '__doc__', None):
@@ -214,6 +265,7 @@ def show_special_methods(app, what, name, obj, skip, options):
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]
     app.add_transform(PrettifySpecialMethods)
+    app.connect('object-description-transform', convert_meta_self_param, priority=450)
     app.setup_extension('sphinx.ext.autodoc')
     app.connect('autodoc-skip-member', show_special_methods)
     return {'version': __version__, 'parallel_read_safe': True}

tests/test-autodoc-self-param/conf.py

@@ -0,0 +1,23 @@
+import sys
+import os
+
+
+doc_module_path = os.path.dirname(__file__)
+if doc_module_path not in sys.path:
+    sys.path.append(doc_module_path)
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.prettyspecialmethods',
+]
+
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'exclude-members': '__weakref__,__dict__,__module__',
+}

tests/test-autodoc-self-param/index.rst

@@ -0,0 +1,4 @@
+.. automodule:: test_autodoc_self_param_module
+   :members:
+   :special-members:
+   :undoc-members:

tests/test-autodoc-self-param/test_autodoc_self_param_module.py

@@ -0,0 +1,225 @@
+class MethodHolder:
+    # misc (alphabetical)
+    def __await__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __call__(self, *args, **kwargs):
+        """:meta self-param: obj"""
+        pass
+
+    def __dir__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __format__(self, fmt):
+        """:meta self-param: obj"""
+        pass
+
+    def __hash__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __repr__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __sizeof__(self):
+        """:meta self-param: obj"""
+        pass
+
+    # type coercion
+
+    def __str__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __bytes__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __bool__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __int__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __float__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __complex__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __index__(self):
+        """:meta self-param: obj"""
+        pass
+
+    # attribute access
+
+    def __getattr__(self, attr):
+        """:meta self-param: obj"""
+        pass
+
+    def __setattr__(self, attr, value):
+        """:meta self-param: obj"""
+        pass
+
+    def __delattr__(self, attr):
+        """:meta self-param: obj"""
+        pass
+
+    # sequence methods
+
+    def __contains__(self, value):
+        """:meta self-param: obj"""
+        pass
+
+    def __getitem__(self, item):
+        """:meta self-param: obj"""
+        pass
+
+    def __setitem__(self, item, value):
+        """:meta self-param: obj"""
+        pass
+
+    def __delitem__(self, item):
+        """:meta self-param: obj"""
+        pass
+
+    def __iter__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __len__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __length_hint__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __reversed__(self):
+        """:meta self-param: obj"""
+        pass
+
+    # unary operators (alphabetical)
+
+    def __invert__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __neg__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __pos__(self):
+        """:meta self-param: obj"""
+        pass
+
+    # binary operators (alphabetical)
+
+    def __add__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __and__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __divmod__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __eq__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __floordiv__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __ge__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __gt__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __le__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __lshift__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __lt__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __matmul__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __mod__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __mul__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __ne__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __or__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __pow__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __rshift__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __sub__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __truediv__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    def __xor__(self, other):
+        """:meta self-param: obj"""
+        pass
+
+    # other math
+
+    def __abs__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __ceil__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __floor__(self):
+        """:meta self-param: obj"""
+        pass
+
+    def __round__(self, n):
+        """:meta self-param: obj"""
+        pass
+
+    def __trunc__(self):
+        """:meta self-param: obj"""
+        pass

tests/test-simple-self-param/conf.py

@@ -0,0 +1,4 @@
+extensions = ['sphinxcontrib.prettyspecialmethods']
+
+# The suffix of source filenames.
+source_suffix = '.rst'