fix: Fix highlighting for signature with known special names like __init__

Issue-mkdocstrings-757: mkdocstrings/mkdocstrings#757

Author: pawamoy

src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -185,10 +185,12 @@ def do_format_signature(
     # Pygments sees it as a function call and not a function definition.
     # The result is that the function name is not parsed as such,
     # but instead as a regular name: `n` CSS class instead of `nf`.
-    # To fix it, we replace the first occurrence of an `n` CSS class
-    # with an `nf` one, unless we found `nf` already.
-    if signature.find('class="nf"') == -1:
-        signature = signature.replace('class="n"', 'class="nf"', 1)
+    # When the function name is a known special name like `__exit__`,
+    # Pygments will set an `fm` (function -> magic) CSS class.
+    # To fix this, we replace the CSS class in the first span with `nf`,
+    # unless we already found an `nf` span.
+    if not re.search(r'<span class="nf">', signature):
+        signature = re.sub(r'<span class="[a-z]+">', '<span class="nf">', signature, count=1)
 
     if stash := env.filters["stash_crossref"].stash:
         for key, value in stash.items():

tests/snapshots/__init__.py

@@ -8,12 +8,12 @@
             ("separate_signature", True),
             ("show_signature_annotations", False),
             ("signature_crossrefs", False),
-        ): external("4370d843cc76*.html"),
+        ): external("d03d16d1919a*.html"),
         (
             ("separate_signature", True),
             ("show_signature_annotations", True),
             ("signature_crossrefs", True),
-        ): external("261a38d7a86b*.html"),
+        ): external("e412376be64f*.html"),
         (
             ("separate_signature", False),
             ("show_signature_annotations", True),
@@ -33,12 +33,12 @@
             ("separate_signature", True),
             ("show_signature_annotations", True),
             ("signature_crossrefs", False),
-        ): external("f5ce06acbb7a*.html"),
+        ): external("74ee37cd1e94*.html"),
         (
             ("separate_signature", True),
             ("show_signature_annotations", False),
             ("signature_crossrefs", True),
-        ): external("9c0bfc0ee407*.html"),
+        ): external("4041a38e355f*.html"),
         (
             ("separate_signature", False),
             ("show_signature_annotations", True),

tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html renamed to tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html

@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">

tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html renamed to tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html

@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">

tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html renamed to tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html

@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">

tests/snapshots/external/261a38d7a86b5e959b6d1c165108301963d0170c2189d5aa18bb7c7eade84ea4.html renamed to tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html

@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="int" optional="">int</autoref></span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="str" optional="">str</autoref></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="int" optional="">int</autoref></span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="str" optional="">str</autoref></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">