feat: include documentation for double-underscore methods when requested

pdoc/__main__.py

@@ -55,6 +55,12 @@
     help="The default docstring format. For non-Markdown formats, pdoc will first convert matching syntax elements to "
     "Markdown and then process everything as Markdown.",
 )
+renderopts.add_argument(
+    "--include-dunder",
+    action=BooleanOptionalAction,
+    default=False,
+    help="Show double-underscore methods that have a docstring.",
+)
 renderopts.add_argument(
     "--include-undocumented",
     action=BooleanOptionalAction,
@@ -182,6 +188,7 @@ def cli(args: list[str] | None = None) -> None:
 
     pdoc.render.configure(
         docformat=opts.docformat,
+        include_dunder=opts.include_dunder,
         include_undocumented=opts.include_undocumented,
         edit_url_map=dict(x.split("=", 1) for x in opts.edit_url),
         favicon=opts.favicon,

pdoc/render.py

@@ -34,6 +34,7 @@ def configure(
     docformat: Literal[
         "markdown", "google", "numpy", "restructuredtext"  # noqa: F821
     ] = "restructuredtext",
+    include_dunder: bool = False,
     include_undocumented: bool = True,
     edit_url_map: Mapping[str, str] | None = None,
     favicon: str | None = None,
@@ -77,6 +78,7 @@ def configure(
     env.loader = FileSystemLoader(searchpath)
 
     env.globals["docformat"] = docformat
+    env.globals["include_dunder"] = include_dunder
     env.globals["include_undocumented"] = include_undocumented
     env.globals["edit_url_map"] = edit_url_map or {}
     env.globals["math"] = math

pdoc/templates/default/module.html.jinja2

@@ -234,7 +234,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% defaultmacro is_public(doc) %}
     {#
     This macro is a bit unconventional in that its output is not rendered, but treated as a boolean:
-    Returning no text is interpreted as false, returning any other text is iterpreted as true.
+    Returning no text is interpreted as false, returning any other text is interpreted as true.
     Implementing this as a macro makes it very easy to override with a custom template, see
     https://github.com/mitmproxy/pdoc/tree/main/examples/custom-template.
     #}
@@ -257,6 +257,9 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {% elif not doc.name.startswith("_") %}
         {# members not starting with an underscore are considered public by default #}
         true
+    {% elif include_dunder and doc.docstring %}
+        {# explicitly include documentation for double-underscore methods if available #}
+	true
     {% endif %}
 {% enddefaultmacro %}
 {# fmt: off #}

test/test_snapshot.py

@@ -169,6 +169,12 @@ def outfile(self, format: str) -> Path:
             "include_undocumented": False,
         },
     ),
+    Snapshot(
+        "dunder",
+        render_options={
+            "include_dunder": True,
+        },
+    ),
 ]
 
 

test/testdata/dunder.py

@@ -0,0 +1,13 @@
+"""
+Example where double-underscore method should be rendered.
+"""
+
+
+class HasDunderMethods:
+    def __eq__(self, other):
+        # Not documented because no docstring.
+        pass
+
+    def __lt__(self, other):
+        """Documented because it has docstring."""
+

test/testdata/dunder.txt

@@ -0,0 +1,5 @@
+<module dunder  # Example where double…
+    <class dunder.HasDunderMethods
+        <method def __init__(): ...>
+    >
+>