78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
|
---
|
|||
|
|
title: Documentation Agent Guide
|
|||
|
|
description: Internal guide for maintaining and improving Instructor documentation
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# AGENT.md - Documentation
|
|||
|
|
|
|||
|
|
## Commands
|
|||
|
|
- Serve docs locally: `uv run mkdocs serve`
|
|||
|
|
- Build docs: `./build_mkdocs.sh` or `uv run mkdocs build`
|
|||
|
|
- Install doc deps: `uv pip install -e ".[docs]"`
|
|||
|
|
- Test examples: `uv run pytest docs/ --examples`
|
|||
|
|
|
|||
|
|
## Structure
|
|||
|
|
- **Core docs**: `concepts/`, `integrations/`, `examples/`
|
|||
|
|
- **Learning path**: `getting-started.md` → `learning/` → `tutorials/`
|
|||
|
|
- **API reference**: Auto-generated from docstrings via `mkdocstrings`
|
|||
|
|
- **Blog**: `blog/posts/` for announcements and deep-dives
|
|||
|
|
- **Templates**: `templates/` for new docs (provider, concept, cookbook)
|
|||
|
|
|
|||
|
|
## Writing Guidelines
|
|||
|
|
- **Reading level**: Grade 10 (from .cursor/rules)
|
|||
|
|
- **Code examples**: Must be runnable with complete imports
|
|||
|
|
- **Progressive complexity**: Simple → advanced concepts
|
|||
|
|
- **Provider docs**: Follow `templates/` patterns
|
|||
|
|
- **Navigation**: Update `mkdocs.yml` for new pages
|
|||
|
|
|
|||
|
|
## Pull Request (PR) Formatting
|
|||
|
|
|
|||
|
|
Use **Conventional Commits** formatting for PR titles so they are consistent and easy to scan. Treat the PR title as the message we would use for a squash merge commit.
|
|||
|
|
|
|||
|
|
### PR Title Format
|
|||
|
|
|
|||
|
|
Use:
|
|||
|
|
|
|||
|
|
`<type>(<scope>): <short summary>`
|
|||
|
|
|
|||
|
|
Rules:
|
|||
|
|
- Keep it under ~70 characters when you can.
|
|||
|
|
- Use the imperative mood (for example, “add”, “fix”, “update”).
|
|||
|
|
- Do not end with a period.
|
|||
|
|
- If it includes a breaking change, add `!` after the type or scope (for example, `feat(docs)!:`).
|
|||
|
|
|
|||
|
|
Good examples:
|
|||
|
|
- `docs(agents): add conventional commit PR title guidelines`
|
|||
|
|
- `docs(mkdocs): fix broken link in validation tutorial`
|
|||
|
|
- `docs(examples): update youtube clips snippet`
|
|||
|
|
- `chore(docs): refresh docs build commands`
|
|||
|
|
|
|||
|
|
Common types:
|
|||
|
|
- `docs`: documentation-only changes
|
|||
|
|
- `fix`: bug fix
|
|||
|
|
- `feat`: new feature
|
|||
|
|
- `test`: add or update tests
|
|||
|
|
- `chore`: maintenance work (build scripts, tooling, repo hygiene)
|
|||
|
|
- `ci`: CI pipeline changes
|
|||
|
|
|
|||
|
|
Suggested docs scopes:
|
|||
|
|
- `docs`, `mkdocs`, `blog`, `examples`, `integrations`, `tutorials`, `agents`
|
|||
|
|
|
|||
|
|
### PR Description Guidelines
|
|||
|
|
|
|||
|
|
Keep PR descriptions short and actionable:
|
|||
|
|
- **What**: What changed, in 1–3 sentences.
|
|||
|
|
- **Why**: Why this change is needed (link issues when possible).
|
|||
|
|
- **Changes**: 3–7 bullet points with the main edits.
|
|||
|
|
- **Testing**: What you ran (or why you did not run anything).
|
|||
|
|
- **Docs impact**: Call out page moves, redirects, or nav updates.
|
|||
|
|
|
|||
|
|
If the PR was authored by Cursor, include:
|
|||
|
|
- `This PR was written by [Cursor](https://cursor.com)`
|
|||
|
|
|
|||
|
|
## Key Files
|
|||
|
|
- `mkdocs.yml` - Site configuration and navigation
|
|||
|
|
- `hooks/` - Custom processing (hide_lines.py removes `# <%hide%>` markers)
|
|||
|
|
- `overrides/` - Custom theme elements
|
|||
|
|
- `javascripts/` - Client-side enhancements
|