fix(pretty): Fix bug where commands and options were displayed in the… (#17)

## Pull Request: Add Support for Parsing and Rendering Command Tables in
Markdown CLI Docs

### Summary

This PR enhances the `pretty.py` module to support parsing and rendering
a **Commands** section in CLI documentation. The changes allow the
system to recognize, store, and output tables of subcommands (with names
and descriptions) in both the markdown-to-tree and tree-to-markdown
conversions.

### Details

- **New Model:**  
- Added a `CommandEntry` Pydantic model to represent individual commands
with `name` and `description` fields.
- Updated the `CommandNode` model to include a `commands:
List[CommandEntry]` field.

- **Markdown Parsing (`parse_markdown_to_tree`):**
  - Recognizes the `**Commands**:` section in markdown.
- Parses each command entry (name and description) and adds it to the
`commands` list of the current command node.
- Handles both the standard `* `name`: description` and fallback `*
`name`` formats.

- **Markdown Rendering (`tree_to_markdown`):**
- Adds a "Commands" table to the generated markdown if any commands are
present.
  - Formats the table with columns for "Name" and "Description".

- **Other Improvements:**
- Ensures section state is correctly managed when switching between
arguments, options, and commands.
  - Adds tests for edge cases in command parsing and rendering.

### Motivation

This change makes the CLI documentation more comprehensive by including
a structured list of subcommands, improving both the parsing of existing
markdown and the generation of new documentation.

### Example

A markdown section like:

```markdown
**Commands**:
* `serve`: Start the server
* `build`: Build the project
```


Will now be parsed into the tree and rendered back as a markdown table.

---

**Closes:** #16

Author: Ox54

.coverage

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-typer2"
-version = "0.1.4"
+version = "0.1.5"
 description = "Mkdocs plugin for generating Typer CLI docs"
 readme = "README.md"
 requires-python = ">=3.10"

pyproject.toml

@@ -11,7 +11,7 @@ def docs(name: str = typer.Option(..., help="The name of the project")):
     print(f"Generating docs for {name}")
 
 
-@app.command()
+@app.command(hidden=True)
 def hello(
     name: Annotated[str, typer.Argument(..., help="The name of the person to greet")],
     caps: Annotated[

src/mkdocs_typer2/cli.py

@@ -18,13 +18,19 @@ class Argument(BaseModel):
     required: bool = False
 
 
+class CommandEntry(BaseModel):
+    name: str
+    description: str = ""
+
+
 class CommandNode(BaseModel):
     name: str
     description: str = ""
     usage: Optional[str] = None
     arguments: List[Argument] = []
     options: List[Option] = []
     subcommands: List["CommandNode"] = []
+    commands: List[CommandEntry] = []
 
 
 def parse_markdown_to_tree(content: str) -> CommandNode:
@@ -68,6 +74,7 @@ def parse_markdown_to_tree(content: str) -> CommandNode:
     current_section = None
     in_description = False
     desc_lines = []
+    in_commands_section = False
 
     i = 0
     while i < len(lines):
@@ -81,6 +88,7 @@ def parse_markdown_to_tree(content: str) -> CommandNode:
             current_command = new_cmd
             in_description = True  # Start capturing description for this command
             desc_lines = []
+            in_commands_section = False
 
         elif (
             in_description
@@ -97,6 +105,7 @@ def parse_markdown_to_tree(content: str) -> CommandNode:
             if in_description and desc_lines:
                 current_command.description = "\n".join(desc_lines)
             in_description = False
+            in_commands_section = False
             # Find the line with usage example
             j = i
             while j < len(lines) and "$ " not in lines[j]:
@@ -110,19 +119,23 @@ def parse_markdown_to_tree(content: str) -> CommandNode:
                 current_command.description = "\n".join(desc_lines)
             in_description = False
             current_section = "arguments"
+            in_commands_section = False
 
         elif line.startswith("**Options**:"):
             # End of description section
             if in_description and desc_lines:
                 current_command.description = "\n".join(desc_lines)
             in_description = False
             current_section = "options"
+            in_commands_section = False
 
         elif line.startswith("**Commands**:"):
-            # End of description section
+            # End of description section, start commands section
             if in_description and desc_lines:
                 current_command.description = "\n".join(desc_lines)
             in_description = False
+            current_section = None
+            in_commands_section = True
 
         elif line.startswith("* `") and current_section == "options":
             # Parse option
@@ -147,6 +160,23 @@ def parse_markdown_to_tree(content: str) -> CommandNode:
                 )
                 current_command.arguments.append(argument)
 
+        elif line.startswith("* `") and in_commands_section:
+            # Parse command name and description
+            match = re.match(r"\* `(.*?)`: (.*)", line)
+            if match:
+                cmd_name, cmd_desc = match.groups()
+                current_command.commands.append(
+                    CommandEntry(name=cmd_name, description=cmd_desc.strip())
+                )
+            else:
+                # Fallback: just the name
+                match = re.match(r"\* `(.*?)`:?", line)
+                if match:
+                    cmd_name = match.group(1)
+                    current_command.commands.append(
+                        CommandEntry(name=cmd_name, description="")
+                    )
+
         i += 1
 
     return root
@@ -191,6 +221,14 @@ def format_options_table(options: list[Option]) -> str:
 
         return "\n".join(rows)
 
+    def format_commands_table(commands: list[CommandEntry]) -> str:
+        if not commands:
+            return "*No commands available*"
+        rows = [format_table_row("Name", "Description"), format_table_row("---", "---")]
+        for cmd in commands:
+            rows.append(format_table_row(f"`{cmd.name}`", cmd.description))
+        return "\n".join(rows)
+
     def format_usage(cmd_name: str, usage: Optional[str]) -> str:
         if not usage:
             return "*No usage specified*"
@@ -213,6 +251,9 @@ def format_usage(cmd_name: str, usage: Optional[str]) -> str:
         "",
         "## Options\n",
         format_options_table(command_node.options),
+        "",
+        "## Commands\n",
+        format_commands_table(command_node.commands),
     ]
 
     # Add subcommands if they exist

src/mkdocs_typer2/pretty.py

@@ -2,6 +2,7 @@
 
 from mkdocs_typer2.pretty import (
     Argument,
+    CommandEntry,
     CommandNode,
     Option,
     parse_markdown_to_tree,
@@ -245,3 +246,40 @@ def test_parse_typer_generated_docs():
     assert len(hello_cmd.options) > 0
     assert any(arg.name == "NAME" for arg in hello_cmd.arguments)
     assert any(opt.name == "--caps / --no-caps" for opt in hello_cmd.options)
+
+
+def test_parse_markdown_with_commands():
+    markdown = """
+# mycli
+
+**Commands**:
+* `foo`: Foo command description
+* `bar`: Bar command description
+"""
+    result = parse_markdown_to_tree(markdown)
+    assert len(result.commands) == 2
+    assert result.commands[0].name == "foo"
+    assert result.commands[0].description == "Foo command description"
+    assert result.commands[1].name == "bar"
+    assert result.commands[1].description == "Bar command description"
+
+
+def test_tree_to_markdown_with_commands():
+    cmd = CommandNode(
+        name="mycli",
+        description="A test CLI",
+        commands=[
+            CommandEntry(name="foo", description="Foo command description"),
+            CommandEntry(name="bar", description="Bar command description"),
+        ],
+    )
+    markdown = tree_to_markdown(cmd)
+    assert "| Name | Description |" in markdown
+    assert "`foo`" in markdown and "Foo command description" in markdown
+    assert "`bar`" in markdown and "Bar command description" in markdown
+
+
+def test_tree_to_markdown_no_commands():
+    cmd = CommandNode(name="mycli", description="A test CLI", commands=[])
+    markdown = tree_to_markdown(cmd)
+    assert "*No commands available*" in markdown