Add docstring transform

Author: kwankyu

src/doc/common/static/custom-furo.css

@@ -21,3 +21,9 @@ a.pdf:hover {
   text-decoration: none;
 }
 
+
+/* For INPUT, OUTPUT, EXAMPLES blocks */
+
+abbr {
+  font-weight: 500;
+}

src/sage_docbuild/conf.py

@@ -853,6 +853,79 @@ def apply(self):
                     node.parent.insert(node.parent.index(node) + 1, cell_node)
 
 
+class DocstringTransform(SphinxTransform):
+   """
+    Transform sections in Sage docstring for better rendering.
+
+    The following are tests:
+
+    AUTHORS:
+
+    - Alice
+    - Bob
+
+    INPUT:
+
+    - one
+    - two
+
+    OUTPUT:
+
+    three
+
+    OUTPUT: three
+
+    EXAMPLE::
+
+        sage: 1 + 2
+        3
+
+    EXAMPLES::
+
+        sage: 1 + 2
+        3
+
+    EXAMPLE:
+
+    We show that `1 + 2 = 3`::
+
+        sage: 1 + 2
+        3
+
+    EXAMPLES:
+
+    We show that `1 + 2 = 3`::
+
+        sage: 1 + 2
+        3
+
+    """
+    default_priority = 800
+
+    def apply(self):
+        for node in self.document.traverse(nodes.paragraph):
+            if isinstance(node.children[0], nodes.Text) and node.children[0].astext().strip() == 'AUTHORS:':
+                list_node = node.next_node(siblings=True, descend=False)
+                if isinstance(list_node, nodes.bullet_list):
+                    new_node = nodes.admonition(classes=['authors'], admonitionclass='authors')
+                    node.replace_self(new_node)
+                    node = new_node
+                    admonition_title = nodes.title()
+                    admonition_title.append(nodes.Text('Authors'))
+                    node.insert(0, admonition_title)
+                    node.append(list_node)
+                    node.parent.remove(list_node)
+            for section in ['INPUT', 'OUTPUT', 'EXAMPLES', 'EXAMPLE']:
+                if isinstance(node.children[0], nodes.Text) and node.children[0].astext().startswith(f'{section}:'):
+                    parent = node.parent
+                    index = parent.index(node)
+                    parent.remove(node)
+                    parent.insert(index, nodes.Text(node.children[0].astext()[len(f'{section}:'):]))
+                    acronym_node = nodes.acronym()
+                    acronym_node += nodes.Text(section)
+                    parent.insert(index, acronym_node)
+
+
 # This replaces the setup() in sage.misc.sagedoc_conf
 def setup(app):
     app.connect('autodoc-process-docstring', process_docstring_cython)
@@ -864,6 +937,7 @@ def setup(app):
         app.connect('autodoc-process-docstring', skip_TESTS_block)
     app.connect('autodoc-skip-member', skip_member)
     app.add_transform(SagemathTransform)
+    app.add_transform(DocstringTransform)
     if os.environ.get('SAGE_LIVE_DOC', 'no') == 'yes':
         app.add_transform(SagecodeTransform)