Add Visibility Modifiers (#578)

* add visibility modifiers

* [autofix.ci] apply automated fixes

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+ - Functions, classes and variables can now be hidden from documentation by adding `@private` to their docstring.
+   ([#578](https://github.com/mitmproxy/pdoc/pull/578), @mhils)
+ - pdoc can now be configured to skip classes/functions/variables without docstrings by passing
+   `--no-include-undocumented`.
+   ([#578](https://github.com/mitmproxy/pdoc/pull/578), @mhils)
  - pdoc now documents variables by default, even if they have no docstring or type annotation.
    Please make yourself heard in [#574](https://github.com/mitmproxy/pdoc/issues/574) if that
    introduces significant issues for your use case.

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-undocumented",
+    action=BooleanOptionalAction,
+    default=True,
+    help="Show classes/functions/variables that do not have a docstring.",
+)
 renderopts.add_argument(
     "-e",
     "--edit-url",
@@ -176,6 +182,7 @@ def cli(args: list[str] | None = None) -> None:
 
     pdoc.render.configure(
         docformat=opts.docformat,
+        include_undocumented=opts.include_undocumented,
         edit_url_map=dict(x.split("=", 1) for x in opts.edit_url),
         favicon=opts.favicon,
         footer_text=opts.footer_text,

pdoc/render.py

@@ -34,6 +34,7 @@ def configure(
     docformat: Literal[
         "markdown", "google", "numpy", "restructuredtext"  # noqa: F821
     ] = "restructuredtext",
+    include_undocumented: bool = True,
     edit_url_map: Mapping[str, str] | None = None,
     favicon: str | None = None,
     footer_text: str = "",
@@ -50,6 +51,7 @@ def configure(
 
     - `docformat` is the docstring flavor in use.
       pdoc prefers plain Markdown (the default), but also supports other formats.
+    - `include_undocumented` controls whether members without a docstring are included in the output.
     - `edit_url_map` is a mapping from module names to URL prefixes. For example,
 
         ```json
@@ -74,8 +76,9 @@ def configure(
         searchpath = [template_directory] + searchpath
     env.loader = FileSystemLoader(searchpath)
 
-    env.globals["edit_url_map"] = edit_url_map or {}
     env.globals["docformat"] = docformat
+    env.globals["include_undocumented"] = include_undocumented
+    env.globals["edit_url_map"] = edit_url_map or {}
     env.globals["math"] = math
     env.globals["mermaid"] = mermaid
     env.globals["show_source"] = show_source

pdoc/templates/default/module.html.jinja2

@@ -238,7 +238,11 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     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.
     #}
-    {% if doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
+    {% if not include_undocumented and not doc.docstring %}
+        {# hide members that are undocumented if include_undocumented has been toggled off. #}
+    {% elif doc.docstring and "@private" in doc.docstring %}
+        {# hide members explicitly marked as @private #}
+    {% elif doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
         {# show constructors that have a docstring or at least one extra argument #}
         true
     {% elif doc.name == "__doc__" %}

test/test_snapshot.py

@@ -162,6 +162,12 @@ def outfile(self, format: str) -> Path:
     Snapshot("top_level_reimports", ["top_level_reimports"]),
     Snapshot("type_checking_imports"),
     Snapshot("type_stub", min_version=(3, 10)),
+    Snapshot(
+        "visibility",
+        render_options={
+            "include_undocumented": False,
+        },
+    ),
 ]
 
 

test/testdata/visibility.py

@@ -0,0 +1,14 @@
+"""
+Example where no children should be rendered.
+"""
+
+
+class Undocumented:
+    # Not shown because no docstring.
+    pass
+
+
+def my_func():
+    """
+    This is a public method that's not shown because it's marked as @private.
+    """

test/testdata/visibility.txt

@@ -0,0 +1,6 @@
+<module visibility  # Example where no chi…
+    <class visibility.Undocumented
+        <method def __init__(): ...>
+    >
+    <function def my_func(): ...  # This is a public met…>
+>