cli docs

[ajspig]

Summary by CodeRabbit

• Documentation
  • Added comprehensive CLI Reference documentation including installation options, configuration precedence rules, and environment variable mappings.
  • Documented all CLI commands and parameters with usage examples.
  • Added workflow guides and scripting examples for automation, CI/CD integration, and non-interactive onboarding.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This PR adds comprehensive CLI documentation for the honcho tool, including a new CLI reference page in the documentation site, a generated command reference snippet, and a Python script that introspects the Typer CLI app to automatically generate structured MDX documentation.

Changes

Cohort / File(s)	Summary
Documentation Navigation docs/docs.json	Added reference to new CLI documentation page entry (v3/documentation/reference/cli) in the v3.0.5 documentation navigation structure.
CLI Reference Documentation docs/v3/documentation/reference/cli.mdx	New comprehensive CLI reference page covering installation via uv tool install and uvx, quick-start commands, configuration resolution precedence, environment variables mapping, workspace/peer/session scoping behavior, TTY vs. JSON output modes, exit codes, and workflow examples including CI/CD usage and scripting patterns.
Generated CLI Commands Snippet docs/snippets/cli-commands.mdx	Auto-generated structured reference documenting all top-level honcho command groups (conclusion, config, doctor, help, init, message, peer, session, workspace) with their invocations, parameters, options, flags, and descriptions using MDX ParamField and AccordionGroup components.
Documentation Generation Tooling honcho-cli/scripts/generate_cli_docs.py	New utility script that introspects the Typer app to generate the CLI commands documentation snippet. Includes helper functions for MDX escaping, Click parameter analysis, command/subcommand rendering with accordion groups, type detection, global option filtering, and supports a --check mode for CI validation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Suggested reviewers

• Rajat-Ahuja1997

Poem

🐰 A CLI guide so neat and grand,
With docs that generate, oh how grand!
From Typer introspection flows the prose,
In MDX snippets, knowledge grows. ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'cli docs' is vague and generic, using non-descriptive terms that don't clearly convey the specific nature of the changes made in this pull request.	Revise the title to be more specific and descriptive, such as 'Add CLI documentation and reference pages' or 'Generate CLI command reference documentation', which better explains the main objectives of adding new CLI documentation pages, reference materials, and a documentation generation script.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch abigail/cli-docs

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

honcho-cli/scripts/generate_cli_docs.py (1)

49-124: Add Google-style docstrings for the remaining functions.

_format_param, _render, build, and main are currently undocumented.

As per coding guidelines "Use Google style docstrings".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@honcho-cli/scripts/generate_cli_docs.py` around lines 49 - 124, Add
Google-style docstrings to the undocumented functions: _format_param(param:
click.Parameter) -> str, _render(cmd: click.Command, path: list[str]) ->
list[str], build() -> str, and main() -> int. For each function add a concise
one-line summary, an Args section documenting parameters and their types (e.g.,
param, cmd, path), a Returns section with the return type and description, and a
Raises section where applicable (e.g., build raising SystemExit). Keep
docstrings in Google style, placed immediately under each function signature,
and ensure private helpers (_format_param, _render) still follow the same
format.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/snippets/cli-commands.mdx`:
- Around line 1-5: The committed generated snippet in
docs/snippets/cli-commands.mdx is out of date; re-run the generator and commit
the updated output by executing the generator
(honcho-cli/scripts/generate_cli_docs.py) with the same flags used in CI (e.g.
run generate_cli_docs.py or run the project's recommended command: uv run
--package honcho-cli python honcho-cli/scripts/generate_cli_docs.py), verify the
file is updated, and commit the regenerated docs; if you want to confirm
consistency locally, run generate_cli_docs.py --check and fix any differences by
re-generating from the source commands in honcho-cli/src/honcho_cli/commands/
before committing.

In `@honcho-cli/scripts/generate_cli_docs.py`:
- Around line 86-88: The doc generator is including hidden commands because the
iteration in _render over cmd.commands and the root-level loop in build do not
check the ClickCommand.hidden flag; update the code in _render (where it loops
over cmd.commands) to skip entries where cmd.commands[sub_name].hidden is True
and likewise filter out hidden commands when build iterates root-level commands
so hidden=True commands are not rendered; additionally add Google-style
docstrings to the functions _format_param, _render, build, and main describing
purpose, args, and returns to meet coding guidelines.

---

Nitpick comments:
In `@honcho-cli/scripts/generate_cli_docs.py`:
- Around line 49-124: Add Google-style docstrings to the undocumented functions:
_format_param(param: click.Parameter) -> str, _render(cmd: click.Command, path:
list[str]) -> list[str], build() -> str, and main() -> int. For each function
add a concise one-line summary, an Args section documenting parameters and their
types (e.g., param, cmd, path), a Returns section with the return type and
description, and a Raises section where applicable (e.g., build raising
SystemExit). Keep docstrings in Google style, placed immediately under each
function signature, and ensure private helpers (_format_param, _render) still
follow the same format.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fd90ef03-42d0-445e-822d-7143f74c2cf8

📥 Commits

Reviewing files that changed from the base of the PR and between 1c3e3f8 and 50ebd24.

📒 Files selected for processing (5)

• .github/workflows/cli-docs.yml
• docs/docs.json
• docs/snippets/cli-commands.mdx
• docs/v3/documentation/reference/cli.mdx
• honcho-cli/scripts/generate_cli_docs.py