emphasize @deprecated decorators

mhils · Oct 11, 2024 · 769fccf · 769fccf
1 parent 9ac4e58
commit 769fccf
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,8 +4,9 @@
 
 ## Unreleased: pdoc next
 
-- Remove support for Python 3.8, which has reached end-of-life on 2024-10-07 .
+- Remove support for Python 3.8, which has reached end-of-life on 2024-10-07.
   ([#747](https://github.com/mitmproxy/pdoc/pull/747), @mhils)
+- Python 3.13: `@deprecated` decorators are now rendered with visual emphasis.
 - Inherited members are now hidden by default if the base class is not part of the documentation.
   Please make yourself heard in https://github.com/mitmproxy/pdoc/issues/715 if you relied on the old behavior.
   ([#748](https://github.com/mitmproxy/pdoc/pull/748), @mhils)

diff --git a/pdoc/templates/content.css b/pdoc/templates/content.css
@@ -308,6 +308,13 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
     margin-left: 2rem;
 }
 
+.pdoc .decorator-deprecated {
+    color: #842029;
+}
+.pdoc .decorator-deprecated ~ span {
+    filter: grayscale(1) opacity(0.8);
+}
+
 .pdoc .name {
     color: var(--name);
     font-weight: bold;

diff --git a/pdoc/templates/default/module.html.jinja2 b/pdoc/templates/default/module.html.jinja2
@@ -162,7 +162,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% enddefaultmacro %}
 {% defaultmacro decorators(doc) %}
     {% for d in doc.decorators if not d.startswith("@_") %}
-        <div class="decorator">{{ d }}</div>
+        <div class="decorator decorator-{{ d[1:].partition("(")[0] }}">{{ d }}</div>
     {% endfor %}
 {% enddefaultmacro %}
 {% defaultmacro function(fn) -%}

diff --git a/test/testdata/misc_py313.html b/test/testdata/misc_py313.html
@@ -35,6 +35,9 @@ <h2>API Documentation</h2>
                 </ul>
 
             </li>
+            <li>
+                    <a class="function" href="#deprecated_func">deprecated_func</a>
+            </li>
     </ul>
 
 
@@ -56,12 +59,20 @@ <h1 class="modulename">
 
                         <label class="view-source-button" for="mod-misc_py313-view-source"><span>View Source</span></label>
 
-                        <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos">1</span></a><span class="k">class</span> <span class="nc">MyDict</span><span class="p">(</span><span class="nb">dict</span><span class="p">):</span>
-</span><span id="L-2"><a href="#L-2"><span class="linenos">2</span></a>    <span class="k">pass</span>
-</span><span id="L-3"><a href="#L-3"><span class="linenos">3</span></a>
-</span><span id="L-4"><a href="#L-4"><span class="linenos">4</span></a>
-</span><span id="L-5"><a href="#L-5"><span class="linenos">5</span></a><span class="k">class</span> <span class="nc">CustomException</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
-</span><span id="L-6"><a href="#L-6"><span class="linenos">6</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;custom exception type&quot;&quot;&quot;</span>
+                        <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos"> 1</span></a><span class="kn">from</span> <span class="nn">warnings</span> <span class="kn">import</span> <span class="n">deprecated</span>
+</span><span id="L-2"><a href="#L-2"><span class="linenos"> 2</span></a>
+</span><span id="L-3"><a href="#L-3"><span class="linenos"> 3</span></a>
+</span><span id="L-4"><a href="#L-4"><span class="linenos"> 4</span></a><span class="k">class</span> <span class="nc">MyDict</span><span class="p">(</span><span class="nb">dict</span><span class="p">):</span>
+</span><span id="L-5"><a href="#L-5"><span class="linenos"> 5</span></a>    <span class="k">pass</span>
+</span><span id="L-6"><a href="#L-6"><span class="linenos"> 6</span></a>
+</span><span id="L-7"><a href="#L-7"><span class="linenos"> 7</span></a>
+</span><span id="L-8"><a href="#L-8"><span class="linenos"> 8</span></a><span class="k">class</span> <span class="nc">CustomException</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
+</span><span id="L-9"><a href="#L-9"><span class="linenos"> 9</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;custom exception type&quot;&quot;&quot;</span>
+</span><span id="L-10"><a href="#L-10"><span class="linenos">10</span></a>
+</span><span id="L-11"><a href="#L-11"><span class="linenos">11</span></a>
+</span><span id="L-12"><a href="#L-12"><span class="linenos">12</span></a><span class="nd">@deprecated</span><span class="p">(</span><span class="s2">&quot;Do not use this anymore&quot;</span><span class="p">)</span>
+</span><span id="L-13"><a href="#L-13"><span class="linenos">13</span></a><span class="k">def</span> <span class="nf">deprecated_func</span><span class="p">():</span>
+</span><span id="L-14"><a href="#L-14"><span class="linenos">14</span></a>    <span class="k">pass</span>
 </span></pre></div>
 
 
@@ -77,8 +88,8 @@ <h1 class="modulename">
 
     </div>
     <a class="headerlink" href="#MyDict"></a>
-            <div class="pdoc-code codehilite"><pre><span></span><span id="MyDict-2"><a href="#MyDict-2"><span class="linenos">2</span></a><span class="k">class</span> <span class="nc">MyDict</span><span class="p">(</span><span class="nb">dict</span><span class="p">):</span>
-</span><span id="MyDict-3"><a href="#MyDict-3"><span class="linenos">3</span></a>    <span class="k">pass</span>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="MyDict-5"><a href="#MyDict-5"><span class="linenos">5</span></a><span class="k">class</span> <span class="nc">MyDict</span><span class="p">(</span><span class="nb">dict</span><span class="p">):</span>
+</span><span id="MyDict-6"><a href="#MyDict-6"><span class="linenos">6</span></a>    <span class="k">pass</span>
 </span></pre></div>
 
 
@@ -96,15 +107,36 @@ <h1 class="modulename">
 
     </div>
     <a class="headerlink" href="#CustomException"></a>
-            <div class="pdoc-code codehilite"><pre><span></span><span id="CustomException-6"><a href="#CustomException-6"><span class="linenos">6</span></a><span class="k">class</span> <span class="nc">CustomException</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
-</span><span id="CustomException-7"><a href="#CustomException-7"><span class="linenos">7</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;custom exception type&quot;&quot;&quot;</span>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="CustomException-9"><a href="#CustomException-9"><span class="linenos"> 9</span></a><span class="k">class</span> <span class="nc">CustomException</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
+</span><span id="CustomException-10"><a href="#CustomException-10"><span class="linenos">10</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;custom exception type&quot;&quot;&quot;</span>
 </span></pre></div>
 
 
             <div class="docstring"><p>custom exception type</p>
 </div>
 
 
+                </section>
+                <section id="deprecated_func">
+                            <input id="deprecated_func-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
+<div class="attr function">
+                    <div class="decorator">@deprecated(&#39;Do not use this anymore&#39;)</div>
+
+        <span class="def">def</span>
+        <span class="name">deprecated_func</span><span class="signature pdoc-code condensed">(<span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="deprecated_func-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#deprecated_func"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="deprecated_func-13"><a href="#deprecated_func-13"><span class="linenos">13</span></a><span class="nd">@deprecated</span><span class="p">(</span><span class="s2">&quot;Do not use this anymore&quot;</span><span class="p">)</span>
+</span><span id="deprecated_func-14"><a href="#deprecated_func-14"><span class="linenos">14</span></a><span class="k">def</span> <span class="nf">deprecated_func</span><span class="p">():</span>
+</span><span id="deprecated_func-15"><a href="#deprecated_func-15"><span class="linenos">15</span></a>    <span class="k">pass</span>
+</span></pre></div>
+
+
+
+
                 </section>
     </main>
 </body>

diff --git a/test/testdata/misc_py313.py b/test/testdata/misc_py313.py
@@ -1,6 +1,14 @@
+from warnings import deprecated
+
+
 class MyDict(dict):
     pass
 
 
 class CustomException(RuntimeError):
     """custom exception type"""
+
+
+@deprecated("Do not use this anymore")
+def deprecated_func():
+    pass
diff --git a/test/testdata/misc_py313.txt b/test/testdata/misc_py313.txt
@@ -18,4 +18,5 @@
         <method def add_note(self, object, /): ...  # inherited from builtins.BaseException.add_note, Exception.add_note(n…>
         <var args  # inherited from builtins.BaseException.args>
     >
+    <@deprecated('Do not use this anymore') function def deprecated_func(): ...>
 >