docs: define canonical docs routing#22
docs: define canonical docs routing#22nsalvacao merged 1 commit intocandidate/lote2-audit-2026-03-16from
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly refactors the project's documentation structure to enhance user experience and clarity. By establishing a single, clear entry point for new users and simplifying the documentation index, it aims to make navigation more intuitive and prevent users from encountering outdated or redundant information. The changes ensure a deterministic path for understanding the project, from initial setup to deeper contributions. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 AI Code Review# Code Review Summary
---
### 🔵 General
- Added explicit error handling for missing root CLI binary in `pipeline.py`.
- Improved error handling in `plugin_generator.py` for JSON loading.
- Removed unused `cli_name` parameter from `_embed_raw` function in `formatter.py`.
---
### 🔴 Critical
- **`_embed_raw` function signature changed but callers updated accordingly.**
No direct issues, but ensure no external callers rely on the old signature with `cli_name`.
- **`shutil.which(cli_name)` check in `crawl_cli`:**
This is a good pre-check, but it only checks PATH availability, not executable permissions or runtime errors.
Consider catching exceptions from `Executor` or subprocess calls for more robust detection.
- **`_is_missing_root_cli_binary` detection relies on stderr/stdout text matching:**
This is fragile and locale-dependent. Consider using exit codes or more reliable detection if possible.
---
### 🟡 Warning
- **Exit code `2` reused in both `pipeline.py` and `plugin_generator.py` for user errors:**
This is fine but document exit codes clearly for maintainability.
- **In `plugin_generator.py`, `parser.exit()` is used for error handling:**
This is acceptable but ensure that `parser` is the `argparse.ArgumentParser` instance and that this behavior is consistent.
- **In `crawl_cli`, `RootCLIBinaryNotFoundError` is raised twice (before and after detection):**
Consider consolidating the logic to avoid duplication.
---
### 🔵 Info / Best Practices
- **Logging error before `sys.exit()` in `main()` is good practice.**
- **Type hints added/improved in `_embed_raw` and other functions.**
- **Use of `Path` and `pathlib` is consistent and modern.**
---
# Summary
The PR improves robustness by adding explicit error handling for missing CLI binaries and JSON loading errors, and cleans up the formatter code by removing an unused parameter. The main security and stability concern is the reliance on string matching for detecting missing binaries, which can be fragile. Consider enhancing detection with exit codes or exceptions. Overall, the changes follow good practices and improve user feedback on errors.
🤖 gpt-4.1-mini · 2042 tokens · GitHub Models free tier · 0 premium requests |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request focuses on improving the onboarding experience by defining a canonical documentation route, primarily through modifications to the README.md and docs/README.md files. The changes aim to guide new users effectively and prevent documentation dead-ends. The review focuses on the clarity and correctness of the changes.
| ## Start Here (Canonical Docs Route) | ||
|
|
||
| If this is your first visit, **this `README.md` is the canonical onboarding path**. | ||
|
|
||
| Follow this order: | ||
|
|
||
| 1. Stay in this file for context + Quick Start. | ||
| 2. Use [`docs/README.md`](docs/README.md) as the docs index for deeper reading. | ||
| 3. Open [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) when you are ready to contribute. | ||
|
|
||
| This keeps first-time navigation deterministic and avoids documentation dead-ends. |
There was a problem hiding this comment.
The added section "Start Here (Canonical Docs Route)" clearly defines the onboarding path for new users. This is a good approach to guide users and avoid confusion. Consider adding a brief explanation of why this order is recommended to further enhance clarity.
| - **First-time user:** `../README.md` -> Quick Start -> Generated Plugin Layout | ||
| - **Contributor:** `../README.md` -> this index -> `CONTRIBUTING.md` | ||
| - **Returning user:** jump directly to the doc above as needed |
There was a problem hiding this comment.
The recommended paths are clearly outlined. Consider adding a brief note about the 'Returning user' path, such as "For experienced users looking for specific information.", to provide additional context.
1 participant
Summary\n- make root README the canonical first-time onboarding path\n- convert docs/README.md into a short routing index\n- remove duplicate long-form onboarding content from docs/README.md to avoid dead-ends\n\n## Validation\n- markdown link validation script for README.md and docs/README.md\n- uv run --extra dev python -m pytest tests/ -q\n- uv run --extra dev ruff check .