Docs: Add classes to C API return value annotations (#117926)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

Author: hugovk

Doc/tools/extensions/c_annotations.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """
     c_annotations.py
     ~~~~~~~~~~~~~~~~
@@ -34,11 +33,10 @@
 
 REST_ROLE_MAP = {
     'function': 'func',
-    'var': 'data',
-    'type': 'type',
     'macro': 'macro',
-    'type': 'type',
     'member': 'member',
+    'type': 'type',
+    'var': 'data',
 }
 
 
@@ -63,15 +61,15 @@ def __init__(self, name):
 class Annotations:
     def __init__(self, refcount_filename, stable_abi_file):
         self.refcount_data = {}
-        with open(refcount_filename, 'r') as fp:
+        with open(refcount_filename, encoding='utf8') as fp:
             for line in fp:
                 line = line.strip()
                 if line[:1] in ("", "#"):
                     # blank lines and comments
                     continue
                 parts = line.split(":", 4)
                 if len(parts) != 5:
-                    raise ValueError("Wrong field count in %r" % line)
+                    raise ValueError(f"Wrong field count in {line!r}")
                 function, type, arg, refcount, comment = parts
                 # Get the entry, creating it if needed:
                 try:
@@ -91,9 +89,8 @@ def __init__(self, refcount_filename, stable_abi_file):
                     entry.result_refs = refcount
 
         self.stable_abi_data = {}
-        with open(stable_abi_file, 'r') as fp:
+        with open(stable_abi_file, encoding='utf8') as fp:
             for record in csv.DictReader(fp):
-                role = record['role']
                 name = record['name']
                 self.stable_abi_data[name] = record
 
@@ -180,13 +177,17 @@ def add_annotations(self, app, doctree):
                 continue
             elif not entry.result_type.endswith("Object*"):
                 continue
+            classes = ['refcount']
             if entry.result_refs is None:
                 rc = sphinx_gettext('Return value: Always NULL.')
+                classes.append('return_null')
             elif entry.result_refs:
                 rc = sphinx_gettext('Return value: New reference.')
+                classes.append('return_new_ref')
             else:
                 rc = sphinx_gettext('Return value: Borrowed reference.')
-            node.insert(0, nodes.emphasis(rc, rc, classes=['refcount']))
+                classes.append('return_borrowed_ref')
+            node.insert(0, nodes.emphasis(rc, rc, classes=classes))
 
 
 def init_annotations(app):
@@ -228,6 +229,7 @@ def setup(app):
         'stableabi': directives.flag,
     }
     old_handle_signature = CObject.handle_signature
+
     def new_handle_signature(self, sig, signode):
         signode.parent['stableabi'] = 'stableabi' in self.options
         return old_handle_signature(self, sig, signode)