Repository navigation
Migrate docs to shared searchable Markdown guides - #30
Conversation
Signed-off-by: PRAMOD B N <pramodbn.boss@gmail.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b329cbb2ef
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 'first-eval': 'getting-started/#your-first-eval-in-60-seconds', | ||
| 'eval-trace': 'core-concepts/#evaltrace-and-evalspan', | ||
| 'test-suite': 'core-concepts/#testsuite-and-testcase', | ||
| evaluators: 'core-concepts/#evaluators', scores: 'core-concepts/#scores-and-reports', |
There was a problem hiding this comment.
For existing bookmarks ending in #breakdowns or #skipped-scores, this route table has no target, so the compatibility script leaves users on the new documentation index instead of the requested section. Both anchors exist in the former guide (docs/docs/index.html), and the breakdowns anchor was also linked from its TestSuite API section. Executing this script with those hashes confirms that neither redirects. Add mappings to core-concepts/#breakdowns-by-metric-and-tag and core-concepts/#skipped-checks to preserve these links during the migration.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical workflow pinning and moderate legacy-anchor redirect issues remain, along with documentation nits.
4 open issues
What changed in this PR
Migrates documentation to searchable Markdown guides using the shared DeepAgentLabs theme while preserving the landing page and legacy bookmarks.
Changes:
- Adds getting-started, concepts, API, advanced, and next-steps guides.
- Adds legacy bookmark redirects.
- Adds strict documentation builds and main-only deployment.
| File | Summary |
|---|---|
docs/next-steps.md |
No findings reported. |
docs/legacy-links.js |
Moderate (1 vote): Add redirects for the legacy #capabilities, #quickstart, and #use-cases anchors. |
docs/index.md |
No findings reported. |
docs/getting-started.md |
No findings reported. |
docs/core-concepts.md |
Nits: Correct Score.metric grouping guidance (1 vote) and add missing snippet imports (2 votes). |
docs/api-reference.md |
Nits: Document keyword-only parameters for Eval (2 votes) and evaluate_suite (1 vote), and clarify min_judge_agreement behavior (1 vote). |
docs/advanced.md |
Nit (4 votes): Add missing TestCase and EvaluatorConfig imports to the custom-evaluator example. |
.github/workflows/docs.yml |
Critical (2 votes): Pin the shared-theme checkout to a reviewed immutable commit instead of mutable main. |
Review effort: Lite
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: DeepAgentLabs/deepagentlabs.github.io | ||
| ref: main |
| EvaluationContext, | ||
| Score, | ||
| EvaluatorRegistry, | ||
| ) |
| ```python | ||
| def Eval( | ||
| name: str, | ||
| data: list[dict] | Callable[[], list[dict]], |
| def cites_order_id(context: EvaluationContext) -> Score: | ||
| order_id = context.case.metadata.get("order_id") |
Replace the single-page HTML documentation presentation with searchable Markdown guides using the shared DeepAgentLabs theme. Preserve the product landing page and redirect existing section bookmarks to the corresponding new guide sections. Publish the compatibility documents alongside getting started, concepts, API reference and advanced evaluation pages.
The first evaluation is now self-contained and runs without credentials: both example cases pass. Documentation builds run on main, pull requests, manual dispatch and daily; only main deploys.
Validation: local Ruff lint/format, mypy, and pytest (291 passed); all six docs build in strict mode and 155 rendered pages pass link/navigation/search/index checks. Browser checks cover shared navigation, theme switching, search results, code-copy controls, old Evals bookmark redirects, mobile navigation and absence of JavaScript errors.