Add support for alternative section names in Google docstrings

CHANGELOG.md

@@ -8,6 +8,9 @@
    ([#474](https://github.com/mitmproxy/pdoc/issues/474), @mhils)
  - Fix broken links for inherited methods if both parent and subclass have the same name.
    ([#493](https://github.com/mitmproxy/pdoc/pull/493), @mhils) 
+ - "Parameters", "Params" and "Arguments" are now also accepted as headings for
+   argument lists in Google-style docstrings.
+   ([#489](https://github.com/mitmproxy/pdoc/pull/489), @ntamas)
 
 ## 2022-11-15: pdoc 12.3.0
 

pdoc/docstrings.py

@@ -85,11 +85,27 @@ def google(docstring: str) -> str:
 
 
 GOOGLE_LIST_SECTIONS = ["Args", "Raises", "Attributes"]
+"""Section headers listed in the official Google docstring style guide."""
+
+GOOGLE_LIST_SECTION_ALIASES = {
+    "Parameters": "Args",
+    "Params": "Args",
+    "Arguments": "Args",
+}
+"""
+Alternative section headers that are not listed in the official Google
+docstring style guide but that we recognize as sections containing lists
+nevertheless.
+"""
 
 
 def _google_section(m: re.Match[str]) -> str:
     name = m.group("name")
     contents = dedent(m.group("contents")).lstrip()
+
+    if name in GOOGLE_LIST_SECTION_ALIASES:
+        name = GOOGLE_LIST_SECTION_ALIASES[name]
+
     if name in GOOGLE_LIST_SECTIONS:
         items = _indented_list(contents)
         contents = ""

test/testdata/flavors_google.html

@@ -98,6 +98,9 @@ <h2>API Documentation</h2>
             <li>
                     <a class="function" href="#newline_after_args">newline_after_args</a>
             </li>
+            <li>
+                    <a class="function" href="#alternative_section_names">alternative_section_names</a>
+            </li>
     </ul>
 
 
@@ -603,6 +606,16 @@ <h6 id="todo">Todo:</h6>
 </span><span id="L-441"><a href="#L-441"><span class="linenos">441</span></a><span class="sd">      test</span>
 </span><span id="L-442"><a href="#L-442"><span class="linenos">442</span></a><span class="sd">        there is unexpected whitespace before test.</span>
 </span><span id="L-443"><a href="#L-443"><span class="linenos">443</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span><span id="L-444"><a href="#L-444"><span class="linenos">444</span></a>
+</span><span id="L-445"><a href="#L-445"><span class="linenos">445</span></a>
+</span><span id="L-446"><a href="#L-446"><span class="linenos">446</span></a><span class="k">def</span> <span class="nf">alternative_section_names</span><span class="p">(</span><span class="n">test</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+</span><span id="L-447"><a href="#L-447"><span class="linenos">447</span></a>    <span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-448"><a href="#L-448"><span class="linenos">448</span></a><span class="sd">    In this example, we check whether alternative section names aliased to</span>
+</span><span id="L-449"><a href="#L-449"><span class="linenos">449</span></a><span class="sd">    &#39;Args&#39; are handled properly.</span>
+</span><span id="L-450"><a href="#L-450"><span class="linenos">450</span></a>
+</span><span id="L-451"><a href="#L-451"><span class="linenos">451</span></a><span class="sd">    Parameters:</span>
+</span><span id="L-452"><a href="#L-452"><span class="linenos">452</span></a><span class="sd">        test: the test string</span>
+</span><span id="L-453"><a href="#L-453"><span class="linenos">453</span></a><span class="sd">    &quot;&quot;&quot;</span>
 </span></pre></div>
 
 
@@ -1728,6 +1741,40 @@ <h6 id="arguments">Arguments:</h6>
 </div>
 
 
+                </section>
+                <section id="alternative_section_names">
+                            <input id="alternative_section_names-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">alternative_section_names</span><span class="signature pdoc-code condensed">(<span class="param"><span class="n">test</span><span class="p">:</span> <span class="nb">str</span></span><span class="return-annotation">):</span></span>
+
+                <label class="view-source-button" for="alternative_section_names-view-source"><span>View Source</span></label>
+
+    </div>
+    <a class="headerlink" href="#alternative_section_names"></a>
+            <div class="pdoc-code codehilite"><pre><span></span><span id="alternative_section_names-447"><a href="#alternative_section_names-447"><span class="linenos">447</span></a><span class="k">def</span> <span class="nf">alternative_section_names</span><span class="p">(</span><span class="n">test</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+</span><span id="alternative_section_names-448"><a href="#alternative_section_names-448"><span class="linenos">448</span></a>    <span class="sd">&quot;&quot;&quot;</span>
+</span><span id="alternative_section_names-449"><a href="#alternative_section_names-449"><span class="linenos">449</span></a><span class="sd">    In this example, we check whether alternative section names aliased to</span>
+</span><span id="alternative_section_names-450"><a href="#alternative_section_names-450"><span class="linenos">450</span></a><span class="sd">    &#39;Args&#39; are handled properly.</span>
+</span><span id="alternative_section_names-451"><a href="#alternative_section_names-451"><span class="linenos">451</span></a>
+</span><span id="alternative_section_names-452"><a href="#alternative_section_names-452"><span class="linenos">452</span></a><span class="sd">    Parameters:</span>
+</span><span id="alternative_section_names-453"><a href="#alternative_section_names-453"><span class="linenos">453</span></a><span class="sd">        test: the test string</span>
+</span><span id="alternative_section_names-454"><a href="#alternative_section_names-454"><span class="linenos">454</span></a><span class="sd">    &quot;&quot;&quot;</span>
+</span></pre></div>
+
+
+            <div class="docstring"><p>In this example, we check whether alternative section names aliased to
+'Args' are handled properly.</p>
+
+<h6 id="arguments">Arguments:</h6>
+
+<ul>
+<li><strong>test:</strong>  the test string</li>
+</ul>
+</div>
+
+
                 </section>
     </main>
 </body>

test/testdata/flavors_google.py

@@ -441,3 +441,14 @@ def newline_after_args(test: str):
       test
         there is unexpected whitespace before test.
     """
+
+
+def alternative_section_names(test: str):
+    """
+    In this example, we check whether alternative section names aliased to
+    'Args' are handled properly.
+
+    Parameters:
+        test: the test string
+    """
+

test/testdata/flavors_google.txt

@@ -39,4 +39,5 @@
         <method def public_method(self): ...  # Performs operation b…>>
     <function def invalid_format(test): ...  # In this example, the…>
     <function def example_code(): ...  # Test case for https:…>
-    <function def newline_after_args(test: str): ...  # Test case for https:…>>
+    <function def newline_after_args(test: str): ...  # Test case for https:…>
+    <function def alternative_section_names(test: str): ...  # In this example, we …>>