Introduce @public marker to explicitly mark members as public

pdoc/__init__.py

@@ -180,9 +180,9 @@ class GoldenRetriever(Dog):
 - If `__all__` is defined in the module, then all identifiers in that list will be considered public.
    No other identifiers will be considered public.
 - If `__all__` is not defined, then pdoc will consider all members public that
-   1. do not start with an underscore,
+   1. do not start with an underscore or have @public in their docstring,
    2. don't have `@private` in their docstring,
-   2. and are defined in the current module (i.e. they are not imported).
+   3. and are defined in the current module (i.e. they are not imported).
 
 In general, we recommend keeping these conventions:
 

pdoc/templates/default/module.html.jinja2

@@ -209,7 +209,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% enddefaultmacro %}
 {% defaultmacro docstring(var) %}
     {% if var.docstring %}
-        <div class="docstring">{{ var.docstring | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
+        <div class="docstring">{{ var.docstring | replace("@public","") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro nav_members(members) %}
@@ -255,6 +255,9 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {% elif (doc.qualname or doc.name) is in(module.obj.__all__ or []) %}
         {# members starting with an underscore are still public if mentioned in __all__ #}
         true
+    {% elif "@public" in doc.docstring %}
+        {# show members explicitly marked as @public #}
+        true
     {% elif not doc.name.startswith("_") %}
         {# members not starting with an underscore are considered public by default #}
         true

test/testdata/visibility.html

@@ -23,6 +23,15 @@
 
             <h2>API Documentation</h2>
                 <ul class="memberlist">
+            <li>
+                    <a class="function" href="#__private_func_explicitly_public">__private_func_explicitly_public</a>
+            </li>
+            <li>
+                    <a class="function" href="#my_other_func">my_other_func</a>
+            </li>
+            <li>
+                    <a class="function" href="#yet_another_func">yet_another_func</a>
+            </li>
     </ul>
 
 
@@ -39,31 +48,145 @@ <h2>API Documentation</h2>
                     <h1 class="modulename">
 visibility    </h1>
 
-                        <div class="docstring"><p>Example where no children should be rendered.</p>
+                        <div class="docstring"><p>Example where only the these children should be rendered:
+    * <code><a href="#__private_func_explicitly_public">__private_func_explicitly_public</a></code>,
+    * <code><a href="#my_other_func">my_other_func</a></code> and
+    * <code><a href="#yet_another_func">yet_another_func</a></code> should be rendered.</p>
 </div>
 
                         <input id="mod-visibility-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 
                         <label class="view-source-button" for="mod-visibility-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="sd">&quot;&quot;&quot;</span>
-</span><span id="L-2"><a href="#L-2"><span class="linenos"> 2</span></a><span class="sd">Example where no children should be rendered.</span>
-</span><span id="L-3"><a href="#L-3"><span class="linenos"> 3</span></a><span class="sd">&quot;&quot;&quot;</span>
-</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><span id="L-6"><a href="#L-6"><span class="linenos"> 6</span></a><span class="k">class</span> <span class="nc">Undocumented</span><span class="p">:</span>
-</span><span id="L-7"><a href="#L-7"><span class="linenos"> 7</span></a>    <span class="c1"># Not shown because no docstring.</span>
-</span><span id="L-8"><a href="#L-8"><span class="linenos"> 8</span></a>    <span class="k">pass</span>
-</span><span id="L-9"><a href="#L-9"><span class="linenos"> 9</span></a>
-</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 class="k">def</span> <span class="nf">my_func</span><span class="p">():</span>
-</span><span id="L-12"><a href="#L-12"><span class="linenos">12</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-</span><span id="L-13"><a href="#L-13"><span class="linenos">13</span></a><span class="sd">    This is a public method that&#39;s not shown because it&#39;s marked as @private.</span>
-</span><span id="L-14"><a href="#L-14"><span class="linenos">14</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-2"><a href="#L-2"><span class="linenos"> 2</span></a><span class="sd">Example where only the these children should be rendered:</span>
+</span><span id="L-3"><a href="#L-3"><span class="linenos"> 3</span></a><span class="sd">    * `__private_func_explicitly_public`,</span>
+</span><span id="L-4"><a href="#L-4"><span class="linenos"> 4</span></a><span class="sd">    * `my_other_func` and</span>
+</span><span id="L-5"><a href="#L-5"><span class="linenos"> 5</span></a><span class="sd">    * `yet_another_func` should be rendered.</span>
+</span><span id="L-6"><a href="#L-6"><span class="linenos"> 6</span></a><span class="sd">&quot;&quot;&quot;</span>
+</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><span id="L-9"><a href="#L-9"><span class="linenos"> 9</span></a><span class="k">class</span> <span class="nc">Undocumented</span><span class="p">:</span>
+</span><span id="L-10"><a href="#L-10"><span class="linenos">10</span></a>    <span class="c1"># Not shown because no docstring.</span>
+</span><span id="L-11"><a href="#L-11"><span class="linenos">11</span></a>    <span class="k">pass</span>
+</span><span id="L-12"><a href="#L-12"><span class="linenos">12</span></a>
+</span><span id="L-13"><a href="#L-13"><span class="linenos">13</span></a>
+</span><span id="L-14"><a href="#L-14"><span class="linenos">14</span></a><span class="k">def</span> <span class="nf">my_func</span><span class="p">():</span>
+</span><span id="L-15"><a href="#L-15"><span class="linenos">15</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-16"><a href="#L-16"><span class="linenos">16</span></a><span class="sd">    This is a public method that&#39;s not shown because it&#39;s marked as @private.</span>
+</span><span id="L-17"><a href="#L-17"><span class="linenos">17</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-18"><a href="#L-18"><span class="linenos">18</span></a>
+</span><span id="L-19"><a href="#L-19"><span class="linenos">19</span></a>
+</span><span id="L-20"><a href="#L-20"><span class="linenos">20</span></a><span class="k">def</span> <span class="nf">__protected_func</span><span class="p">():</span>
+</span><span id="L-21"><a href="#L-21"><span class="linenos">21</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-22"><a href="#L-22"><span class="linenos">22</span></a><span class="sd">    This is a protected method that&#39;s not shown because its name starts with _.</span>
+</span><span id="L-23"><a href="#L-23"><span class="linenos">23</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-24"><a href="#L-24"><span class="linenos">24</span></a>
+</span><span id="L-25"><a href="#L-25"><span class="linenos">25</span></a>
+</span><span id="L-26"><a href="#L-26"><span class="linenos">26</span></a><span class="k">def</span> <span class="nf">__private_func</span><span class="p">():</span>
+</span><span id="L-27"><a href="#L-27"><span class="linenos">27</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-28"><a href="#L-28"><span class="linenos">28</span></a><span class="sd">    This is a private method that&#39;s not shown because its name starts with __.</span>
+</span><span id="L-29"><a href="#L-29"><span class="linenos">29</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-30"><a href="#L-30"><span class="linenos">30</span></a>
+</span><span id="L-31"><a href="#L-31"><span class="linenos">31</span></a>
+</span><span id="L-32"><a href="#L-32"><span class="linenos">32</span></a><span class="k">def</span> <span class="nf">__private_func_explicitly_public</span><span class="p">():</span>
+</span><span id="L-33"><a href="#L-33"><span class="linenos">33</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-34"><a href="#L-34"><span class="linenos">34</span></a><span class="sd">    This is a private method that&#39;s shown because it is explicitly marked</span>
+</span><span id="L-35"><a href="#L-35"><span class="linenos">35</span></a><span class="sd">    as public.</span>
+</span><span id="L-36"><a href="#L-36"><span class="linenos">36</span></a><span class="sd">    @public&quot;&quot;&quot;</span>
+</span><span id="L-37"><a href="#L-37"><span class="linenos">37</span></a>
+</span><span id="L-38"><a href="#L-38"><span class="linenos">38</span></a>
+</span><span id="L-39"><a href="#L-39"><span class="linenos">39</span></a><span class="k">def</span> <span class="nf">my_other_func</span><span class="p">():</span>
+</span><span id="L-40"><a href="#L-40"><span class="linenos">40</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-41"><a href="#L-41"><span class="linenos">41</span></a><span class="sd">    This is another public method that&#39;s shown. It should show without additional</span>
+</span><span id="L-42"><a href="#L-42"><span class="linenos">42</span></a><span class="sd">    whitespace above.</span>
+</span><span id="L-43"><a href="#L-43"><span class="linenos">43</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-44"><a href="#L-44"><span class="linenos">44</span></a>
+</span><span id="L-45"><a href="#L-45"><span class="linenos">45</span></a>
+</span><span id="L-46"><a href="#L-46"><span class="linenos">46</span></a><span class="k">def</span> <span class="nf">yet_another_func</span><span class="p">():</span>
+</span><span id="L-47"><a href="#L-47"><span class="linenos">47</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-48"><a href="#L-48"><span class="linenos">48</span></a><span class="sd">    This is yet another public method to give a gauge for the expected amount of</span>
+</span><span id="L-49"><a href="#L-49"><span class="linenos">49</span></a><span class="sd">    whitespace between too methods.</span>
+</span><span id="L-50"><a href="#L-50"><span class="linenos">50</span></a><span class="sd">    &quot;&quot;&quot;</span>
 </span></pre></div>
 
 
             </section>
+                <section id="__private_func_explicitly_public">
+                            <input id="__private_func_explicitly_public-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
+<div class="attr function">
+
+        <span class="def">def</span>
+        <span class="name">__private_func_explicitly_public</span><span class="signature pdoc-code condensed">(<span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="__private_func_explicitly_public-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#__private_func_explicitly_public"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="__private_func_explicitly_public-33"><a href="#__private_func_explicitly_public-33"><span class="linenos">33</span></a><span class="k">def</span> <span class="nf">__private_func_explicitly_public</span><span class="p">():</span>
+</span><span id="__private_func_explicitly_public-34"><a href="#__private_func_explicitly_public-34"><span class="linenos">34</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="__private_func_explicitly_public-35"><a href="#__private_func_explicitly_public-35"><span class="linenos">35</span></a><span class="sd">    This is a private method that&#39;s shown because it is explicitly marked</span>
+</span><span id="__private_func_explicitly_public-36"><a href="#__private_func_explicitly_public-36"><span class="linenos">36</span></a><span class="sd">    as public.</span>
+</span><span id="__private_func_explicitly_public-37"><a href="#__private_func_explicitly_public-37"><span class="linenos">37</span></a><span class="sd">    @public&quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>This is a private method that's shown because it is explicitly marked
+as public.</p>
+</div>
+
+
+                </section>
+                <section id="my_other_func">
+                            <input id="my_other_func-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
+<div class="attr function">
+
+        <span class="def">def</span>
+        <span class="name">my_other_func</span><span class="signature pdoc-code condensed">(<span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="my_other_func-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#my_other_func"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="my_other_func-40"><a href="#my_other_func-40"><span class="linenos">40</span></a><span class="k">def</span> <span class="nf">my_other_func</span><span class="p">():</span>
+</span><span id="my_other_func-41"><a href="#my_other_func-41"><span class="linenos">41</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="my_other_func-42"><a href="#my_other_func-42"><span class="linenos">42</span></a><span class="sd">    This is another public method that&#39;s shown. It should show without additional</span>
+</span><span id="my_other_func-43"><a href="#my_other_func-43"><span class="linenos">43</span></a><span class="sd">    whitespace above.</span>
+</span><span id="my_other_func-44"><a href="#my_other_func-44"><span class="linenos">44</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>This is another public method that's shown. It should show without additional
+whitespace above.</p>
+</div>
+
+
+                </section>
+                <section id="yet_another_func">
+                            <input id="yet_another_func-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
+<div class="attr function">
+
+        <span class="def">def</span>
+        <span class="name">yet_another_func</span><span class="signature pdoc-code condensed">(<span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="yet_another_func-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#yet_another_func"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="yet_another_func-47"><a href="#yet_another_func-47"><span class="linenos">47</span></a><span class="k">def</span> <span class="nf">yet_another_func</span><span class="p">():</span>
+</span><span id="yet_another_func-48"><a href="#yet_another_func-48"><span class="linenos">48</span></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="yet_another_func-49"><a href="#yet_another_func-49"><span class="linenos">49</span></a><span class="sd">    This is yet another public method to give a gauge for the expected amount of</span>
+</span><span id="yet_another_func-50"><a href="#yet_another_func-50"><span class="linenos">50</span></a><span class="sd">    whitespace between too methods.</span>
+</span><span id="yet_another_func-51"><a href="#yet_another_func-51"><span class="linenos">51</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>This is yet another public method to give a gauge for the expected amount of
+whitespace between too methods.</p>
+</div>
+
+
+                </section>
     </main>
 </body>
 </html>

test/testdata/visibility.py

@@ -1,5 +1,8 @@
 """
-Example where no children should be rendered.
+Example where only the these children should be rendered:
+    * `__private_func_explicitly_public`,
+    * `my_other_func` and
+    * `yet_another_func` should be rendered.
 """
 
 
@@ -12,3 +15,36 @@ def my_func():
     """
     This is a public method that's not shown because it's marked as @private.
     """
+
+
+def __protected_func():
+    """
+    This is a protected method that's not shown because its name starts with _.
+    """
+
+
+def __private_func():
+    """
+    This is a private method that's not shown because its name starts with __.
+    """
+
+
+def __private_func_explicitly_public():
+    """
+    This is a private method that's shown because it is explicitly marked
+    as public.
+    @public"""
+
+
+def my_other_func():
+    """
+    This is another public method that's shown. It should show without additional
+    whitespace above.
+    """
+
+
+def yet_another_func():
+    """
+    This is yet another public method to give a gauge for the expected amount of
+    whitespace between too methods.
+    """

test/testdata/visibility.txt

@@ -1,6 +1,8 @@
-<module visibility  # Example where no chi…
+<module visibility  # Example where only t…
     <class visibility.Undocumented
         <method def __init__(): ...>
     >
     <function def my_func(): ...  # This is a public met…>
+    <function def my_other_func(): ...  # This is another publ…>
+    <function def yet_another_func(): ...  # This is yet another …>
 >