Add show_hidden option (#52)

* Add show_hidden option

* Applied formatting

* Add test for _show_options()

Author: jan-golda

README.md

@@ -135,3 +135,4 @@ Options:
 - `depth`: _(Optional, default: `0`)_ Offset to add when generating headers.
 - `style`: _(Optional, default: `plain`)_ Style for the options section. The possible choices are `plain` and `table`.
 - `remove_ascii_art`: _(Optional, default: `False`)_ When docstrings begin with the escape character `\b`, all text will be ignored until the next blank line is encountered.
+- `show_hidden`: _(Optional, default: `False`)_ Show commands and options that are marked as hidden.

mkdocs_click/_docs.py

@@ -2,6 +2,7 @@
 # All rights reserved
 # Licensed under the Apache license (see LICENSE)
 import inspect
+from contextlib import contextmanager, ExitStack
 from typing import Iterator, List, cast
 
 import click
@@ -16,11 +17,18 @@ def make_command_docs(
     depth: int = 0,
     style: str = "plain",
     remove_ascii_art: bool = False,
+    show_hidden: bool = False,
     has_attr_list: bool = False,
 ) -> Iterator[str]:
     """Create the Markdown lines for a command and its sub-commands."""
     for line in _recursively_make_command_docs(
-        prog_name, command, depth=depth, style=style, remove_ascii_art=remove_ascii_art, has_attr_list=has_attr_list
+        prog_name,
+        command,
+        depth=depth,
+        style=style,
+        remove_ascii_art=remove_ascii_art,
+        show_hidden=show_hidden,
+        has_attr_list=has_attr_list,
     ):
         if line.strip() == "\b":
             continue
@@ -35,21 +43,31 @@ def _recursively_make_command_docs(
     depth: int = 0,
     style: str = "plain",
     remove_ascii_art: bool = False,
+    show_hidden: bool = False,
     has_attr_list: bool = False,
 ) -> Iterator[str]:
     """Create the raw Markdown lines for a command and its sub-commands."""
     ctx = click.Context(cast(click.Command, command), info_name=prog_name, parent=parent)
 
+    if ctx.command.hidden and not show_hidden:
+        return
+
     yield from _make_title(ctx, depth, has_attr_list=has_attr_list)
     yield from _make_description(ctx, remove_ascii_art=remove_ascii_art)
     yield from _make_usage(ctx)
-    yield from _make_options(ctx, style)
+    yield from _make_options(ctx, style, show_hidden=show_hidden)
 
     subcommands = _get_sub_commands(ctx.command, ctx)
 
     for command in sorted(subcommands, key=lambda cmd: cmd.name):  # type: ignore
         yield from _recursively_make_command_docs(
-            cast(str, command.name), command, parent=ctx, depth=depth + 1, style=style, has_attr_list=has_attr_list
+            cast(str, command.name),
+            command,
+            parent=ctx,
+            depth=depth + 1,
+            style=style,
+            show_hidden=show_hidden,
+            has_attr_list=has_attr_list,
         )
 
 
@@ -152,37 +170,55 @@ def _make_usage(ctx: click.Context) -> Iterator[str]:
     yield ""
 
 
-def _make_options(ctx: click.Context, style: str = "plain") -> Iterator[str]:
+def _make_options(ctx: click.Context, style: str = "plain", show_hidden: bool = False) -> Iterator[str]:
     """Create the Markdown lines describing the options for the command."""
 
     if style == "plain":
-        return _make_plain_options(ctx)
+        return _make_plain_options(ctx, show_hidden=show_hidden)
     elif style == "table":
-        return _make_table_options(ctx)
+        return _make_table_options(ctx, show_hidden=show_hidden)
     else:
         raise MkDocsClickException(f"{style} is not a valid option style, which must be either `plain` or `table`.")
 
 
-def _make_plain_options(ctx: click.Context) -> Iterator[str]:
+@contextmanager
+def _show_options(ctx: click.Context) -> Iterator[None]:
+    """Context manager that temporarily shows all hidden options."""
+    options = [opt for opt in ctx.command.get_params(ctx) if isinstance(opt, click.Option) and opt.hidden]
+
+    try:
+        for option in options:
+            option.hidden = False
+        yield
+    finally:
+        for option in options:
+            option.hidden = True
+
+
+def _make_plain_options(ctx: click.Context, show_hidden: bool = False) -> Iterator[str]:
     """Create the plain style options description."""
-    formatter = ctx.make_formatter()
-    click.Command.format_options(ctx.command, ctx, formatter)
+    with ExitStack() as stack:
+        if show_hidden:
+            stack.enter_context(_show_options(ctx))
 
-    option_lines = formatter.getvalue().splitlines()
+        formatter = ctx.make_formatter()
+        click.Command.format_options(ctx.command, ctx, formatter)
 
-    # First line is redundant "Options"
-    option_lines = option_lines[1:]
+        option_lines = formatter.getvalue().splitlines()
 
-    if not option_lines:  # pragma: no cover
-        # We expect at least `--help` to be present.
-        raise RuntimeError("Expected at least one option")
+        # First line is redundant "Options"
+        option_lines = option_lines[1:]
 
-    yield "**Options:**"
-    yield ""
-    yield "```"
-    yield from option_lines
-    yield "```"
-    yield ""
+        if not option_lines:  # pragma: no cover
+            # We expect at least `--help` to be present.
+            raise RuntimeError("Expected at least one option")
+
+        yield "**Options:**"
+        yield ""
+        yield "```"
+        yield from option_lines
+        yield "```"
+        yield ""
 
 
 # Unicode "Vertical Line" character (U+007C), HTML-compatible.
@@ -251,10 +287,11 @@ def _format_table_option_row(option: click.Option) -> str:
     return f"| {names} | {value_type} | {description} | {default} |"
 
 
-def _make_table_options(ctx: click.Context) -> Iterator[str]:
+def _make_table_options(ctx: click.Context, show_hidden: bool = False) -> Iterator[str]:
     """Create the table style options description."""
 
     options = [param for param in ctx.command.get_params(ctx) if isinstance(param, click.Option)]
+    options = [option for option in options if not option.hidden or show_hidden]
     option_rows = [_format_table_option_row(option) for option in options]
 
     yield "**Options:**"

mkdocs_click/_extension.py

@@ -24,6 +24,7 @@ def replace_command_docs(has_attr_list: bool = False, **options: Any) -> Iterato
     depth = int(options.get("depth", 0))
     style = options.get("style", "plain")
     remove_ascii_art = options.get("remove_ascii_art", False)
+    show_hidden = options.get("show_hidden", False)
 
     command_obj = load_command(module, command)
 
@@ -35,6 +36,7 @@ def replace_command_docs(has_attr_list: bool = False, **options: Any) -> Iterato
         depth=depth,
         style=style,
         remove_ascii_art=remove_ascii_art,
+        show_hidden=show_hidden,
         has_attr_list=has_attr_list,
     )
 

tests/app/cli.py

@@ -9,7 +9,8 @@
 @click.command()
 @click.option("--count", default=1, help="Number of greetings.")
 @click.option("--name", prompt="Your name", help="The person to greet.")
-def hello(count, name):
+@click.option("--hidden", hidden=True)
+def hello(count, name, hidden):
     """Simple program that greets NAME for a total of COUNT times."""
 
 
@@ -33,13 +34,20 @@ def bar():
     """The bar command"""
 
 
+@click.command(hidden=True)
+def hidden():
+    """The hidden command"""
+
+
 bar.add_command(hello)
 
 cli.add_command(foo)
 cli.add_command(bar)
+cli.add_command(hidden)
 
 cli_named.add_command(foo)
 cli_named.add_command(bar)
+cli_named.add_command(hidden)
 
 
 class MultiCLI(click.MultiCommand):

tests/test_docs.py

@@ -2,11 +2,12 @@
 # All rights reserved
 # Licensed under the Apache license (see LICENSE)
 from textwrap import dedent
+from typing import cast
 
 import click
 import pytest
 
-from mkdocs_click._docs import make_command_docs
+from mkdocs_click._docs import make_command_docs, _show_options
 from mkdocs_click._exceptions import MkDocsClickException
 
 
@@ -231,3 +232,61 @@ def test_custom_multicommand(multi):
 
     output = "\n".join(make_command_docs("multi", multi))
     assert output == expected
+
+
+@pytest.mark.parametrize("show_hidden", [True, False])
+@pytest.mark.parametrize("style", ["plain", "table"])
+def test_show_hidden_option(show_hidden, style):
+    @click.command()
+    @click.option("--hidden", hidden=True)
+    def _test_cmd(hidden):
+        """Test cmd."""
+
+    output = "\n".join(make_command_docs("_test_cmd", _test_cmd, style=style, show_hidden=show_hidden))
+    assert ("--hidden" in output) == show_hidden
+
+
+@pytest.mark.parametrize("show_hidden", [True, False])
+def test_show_hidden_command(show_hidden):
+    @click.command(hidden=True)
+    def _test_cmd():
+        """Test cmd."""
+
+    output = "\n".join(make_command_docs("_test_cmd", _test_cmd, show_hidden=show_hidden))
+    assert (output != "") == show_hidden
+
+
+@pytest.mark.parametrize("show_hidden", [True, False])
+def test_show_hidden_group(show_hidden):
+    @click.group(hidden=True)
+    def _test_group():
+        """Test group."""
+
+    @_test_group.command(hidden=False)
+    def _test_cmd():
+        """Test cmd."""
+
+    output = "\n".join(make_command_docs("_test_group", _test_group, show_hidden=show_hidden))
+    assert (output != "") == show_hidden
+
+
+def test_show_options():
+    @click.command()
+    @click.option("--hidden", hidden=True)
+    @click.option("--normal", hidden=False)
+    def _test_cmd(hidden, normal):
+        """Test cmd."""
+
+    ctx = click.Context(cast(click.Command, _test_cmd), info_name="_test_cmd")
+    opt_hidden = cast(click.Option, ctx.command.params[0])
+    opt_normal = cast(click.Option, ctx.command.params[1])
+
+    assert opt_hidden.hidden
+    assert not opt_normal.hidden
+
+    with _show_options(ctx):
+        assert not opt_hidden.hidden
+        assert not opt_normal.hidden
+
+    assert opt_hidden.hidden
+    assert not opt_normal.hidden