Improve the displayed signature for abstract methods

Author: AA-Turner

doc/usage/domains/python.rst

@@ -324,6 +324,13 @@ The following directives are provided for module and class contents:
       :type: no value
 
       Indicate the property is abstract.
+      This produces the following output:
+
+      .. py:property:: Cheese.amount_in_stock
+         :no-index:
+         :abstractmethod:
+
+         Cheese levels at the *National Cheese Emporium*.
 
    .. rst:directive:option:: classmethod
       :type: no value
@@ -416,6 +423,13 @@ The following directives are provided for module and class contents:
       :type: no value
 
       Indicate the method is an abstract method.
+      This produces the following output:
+
+      .. py:method:: Cheese.order_more_stock
+         :no-index:
+         :abstractmethod:
+
+         Order more cheese (we're fresh out!).
 
       .. versionadded:: 2.1
 

sphinx/domains/python/__init__.py

@@ -88,13 +88,13 @@ class PyFunction(PyObject):
     })
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
+        prefix: list[addnodes.desc_sig_element] = []
         if 'async' in self.options:
-            return [
+            prefix.extend((
                 addnodes.desc_sig_keyword('', 'async'),
                 addnodes.desc_sig_space(),
-            ]
-        else:
-            return []
+            ))
+        return prefix
 
     def needs_arglist(self) -> bool:
         return True
@@ -192,15 +192,17 @@ class PyClasslike(PyObject):
     allow_nesting = True
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
+        prefix: list[addnodes.desc_sig_element] = []
         if 'final' in self.options:
-            return [
-                nodes.Text('final'),
-                addnodes.desc_sig_space(),
-                nodes.Text(self.objtype),
+            prefix.extend((
+                addnodes.desc_sig_keyword('', 'final'),
                 addnodes.desc_sig_space(),
-            ]
-        else:
-            return [nodes.Text(self.objtype), addnodes.desc_sig_space()]
+            ))
+        prefix.extend((
+            addnodes.desc_sig_keyword('', self.objtype),
+            addnodes.desc_sig_space(),
+        ))
+        return prefix
 
     def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
         if self.objtype == 'class':
@@ -229,30 +231,30 @@ def needs_arglist(self) -> bool:
         return True
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        prefix: list[nodes.Node] = []
+        prefix: list[addnodes.desc_sig_element] = []
         if 'final' in self.options:
             prefix.extend((
-                nodes.Text('final'),
+                addnodes.desc_sig_keyword('', 'final'),
                 addnodes.desc_sig_space(),
             ))
         if 'abstractmethod' in self.options:
             prefix.extend((
-                nodes.Text('abstract'),
+                addnodes.desc_sig_keyword('', 'abstractmethod'),
                 addnodes.desc_sig_space(),
             ))
         if 'async' in self.options:
             prefix.extend((
-                nodes.Text('async'),
+                addnodes.desc_sig_keyword('', 'async'),
                 addnodes.desc_sig_space(),
             ))
         if 'classmethod' in self.options:
             prefix.extend((
-                nodes.Text('classmethod'),
+                addnodes.desc_sig_keyword('', 'classmethod'),
                 addnodes.desc_sig_space(),
             ))
         if 'staticmethod' in self.options:
             prefix.extend((
-                nodes.Text('static'),
+                addnodes.desc_sig_keyword('', 'static'),
                 addnodes.desc_sig_space(),
             ))
         return prefix
@@ -395,20 +397,19 @@ def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]
         return fullname, prefix
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        prefix: list[nodes.Node] = []
+        prefix: list[addnodes.desc_sig_element] = []
         if 'abstractmethod' in self.options:
             prefix.extend((
-                nodes.Text('abstract'),
+                addnodes.desc_sig_keyword('', 'abstract'),
                 addnodes.desc_sig_space(),
             ))
         if 'classmethod' in self.options:
             prefix.extend((
-                nodes.Text('class'),
+                addnodes.desc_sig_keyword('', 'class'),
                 addnodes.desc_sig_space(),
             ))
-
         prefix.extend((
-            nodes.Text('property'),
+            addnodes.desc_sig_keyword('', 'property'),
             addnodes.desc_sig_space(),
         ))
         return prefix
@@ -437,7 +438,7 @@ class PyTypeAlias(PyObject):
     })
 
     def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
-        return [nodes.Text('type'), addnodes.desc_sig_space()]
+        return [addnodes.desc_sig_keyword('', 'type'), addnodes.desc_sig_space()]
 
     def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
         fullname, prefix = super().handle_signature(sig, signode)

tests/test_domains/test_domain_py_fields.py

@@ -51,7 +51,10 @@ def test_info_field_list(app):
                     [
                         desc_signature,
                         (
-                            [desc_annotation, ('class', desc_sig_space)],
+                            [
+                                desc_annotation,
+                                ([desc_sig_keyword, 'class'], desc_sig_space),
+                            ],
                             [desc_addname, 'example.'],
                             [desc_name, 'Class'],
                         ),
@@ -220,7 +223,10 @@ def test_info_field_list_piped_type(app):
                     [
                         desc_signature,
                         (
-                            [desc_annotation, ('class', desc_sig_space)],
+                            [
+                                desc_annotation,
+                                ([desc_sig_keyword, 'class'], desc_sig_space),
+                            ],
                             [desc_addname, 'example.'],
                             [desc_name, 'Class'],
                         ),
@@ -294,7 +300,10 @@ def test_info_field_list_Literal(app):
                     [
                         desc_signature,
                         (
-                            [desc_annotation, ('class', desc_sig_space)],
+                            [
+                                desc_annotation,
+                                ([desc_sig_keyword, 'class'], desc_sig_space),
+                            ],
                             [desc_addname, 'example.'],
                             [desc_name, 'Class'],
                         ),