diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..345cc2d --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,237 @@ +# Kernel Team Internal Documentation - Copilot Instructions + +## Project Overview + +This is the **Kernel team's internal documentation** - a Sphinx-based documentation project using the [Canonical Sphinx Stack](https://github.com/canonical/sphinx-stack). +Documentation targets the kernel team's documentation processes, standards, and best practices for maintaining the Ubuntu kernels. + +### Repository scope + +This is a docs-only repository. +It contains documentation content and documentation tooling only. +There is no product runtime or application source code in scope for behavior verification. + +When verifying documentation accuracy, treat repository artifacts as the source of truth: +`docs/conf.py`, `docs/Makefile` targets, Sphinx configuration, examples, redirects, +and consistency across documentation pages. + +## Architecture & Structure + +### Diátaxis Framework + +Content is organized using the [Diátaxis framework](https://diataxis.fr/): + +- `tutorial/` - Getting started guides (for example, `crank-your-first-kernel.md`). +- `how-to/` - Task-oriented guides organized by topic or stages of kernel development (for example, stable updates, testing, and development). +- `explanation/` - Conceptual overviews and background information. +- `reference/` - Technical specifications, glossaries, and system requirements. + +### File Types + +- **Markdown (`.md`)** - Primary format for content pages with MyST syntax support. +- **reStructuredText (`.rst`)** - Landing pages, index files, and content pages. +- Mixed content: both formats coexist and are processed by Sphinx. + +### Repository layout + +- `docs/` - Documentation root. +- `docs/tutorial/` - Tutorials and onboarding guides. +- `docs/how-to/` - Task-oriented operational guides. +- `docs/explanation/` - Conceptual and background documentation. +- `docs/reference/` - Specifications, glossary entries, and reference material. +- `docs/reuse/` - Shared links and reusable documentation snippets. +- `docs/conf.py` - Sphinx project configuration, including redirects. +- `docs/Makefile` - Documentation build, test, and local serve targets. + +### Key Configuration Files + +- `docs/conf.py` - Project-specific settings. +- `docs/Makefile` - Build system. +- `docs/.readthedocs.yaml` - Read the Docs build configuration. + +## Development Workflow + +### Local Setup + +```bash +git clone https://github.com/canonical/kernel-docs.git +cd kernel-docs/docs +sudo apt update +sudo apt install make python3 python3-venv python3-pip +make install +``` + +### Build & Preview + +```bash +make run # Build, watch, and serve at http://127.0.0.1:8000 +make html # Build only +make serve # Serve only +make clean-doc # Clean built files +``` + +For remote/VM development, set `export SPHINX_HOST=0.0.0.0` before running `make run`. + +### Testing & Quality Checks + +```bash +make spelling # Spell check (uses .custom_wordlist.txt for exceptions) +make linkcheck # Verify all links +make lint-md # Check Markdown formatting and MyST syntax +make vale # Check style guide compliance (Canonical Vale rules) +make html # Build docs and surface Sphinx warnings/errors +make woke # Check inclusive language +make pa11y # Accessibility testing +``` + +During development, run the checks that match the files you changed. +Before submitting a PR, always run `make spelling`, `make linkcheck`, `make lint-md`, `make vale`, and `make html`. + +## Writing Conventions + +### Style & Language + +- Follow the [Canonical documentation style guide](https://docs.ubuntu.com/styleguide/en). +- Use **US English** (`en-US`). +- Acronyms: expand on first use, for example, "Yet Another Markup Language (YAML)." +- Add technical terms to `docs/reference/glossary.md` and spell exceptions to `docs/.custom_wordlist.txt`. + +### Cross-References + +- Prefix all labels with the Diátaxis section to avoid clashes across pages. + - Recommended short prefixes: `tutorial-*`, `how-to-*`, `exp-*`, `ref-*`. +- In `.rst` files, define labels with section-prefixed names: + - `.. _how-to-label:` +- In `.rst` files, link with `:ref:\`label-name\`` and `:doc:\`/path/to/page\`` for internal pages. +- In `.md` (MyST) files, define labels near the top of the page with section-prefixed names: + - `(how-to-label)=` +- In `.md` (MyST) files, use `{ref}` for labels and `{doc}` for internal page links. +- Prefer native internal cross-references (`:ref:`, `:doc:`, `{ref}`, `{doc}`) over plain relative links so broken links surface during `make run` and `make html`. +- First mentions of packages and tools should link to official documentation or manpages. +- Use semantic markup: `{kbd}\`Ctrl\``, `{manpage}\`dpkg(1)\``, `{term}\`DAC\``. +- Manpage links auto-generate URLs (no hardcoding needed). + +### Formatting Rules + +- Blank line required after every heading before content. +- Blank line required before every list (bullet or numbered). +- Use sentence case for headings, not title case. +- Active voice preferred: "This command does X" not "X is done by this command". +- In `.md` files, use MyST admonition syntax: `` ```{note} ``, `` ```{warning} ``, `` ```{important} ``. +- In `.rst` files, use RST admonition syntax: `.. note::`, `.. warning::`, `.. important::`. + +### Markdown Elements + +- **Headings**: Use proper hierarchy (`#`, `##`, `###`, `####`); don't skip levels. +- **Lists**: Use `1.` for all numbered items (auto-renumbers). +- **Code blocks**: Specify language for syntax highlighting. +- **MyST extensions**: `attrs_block`, `attrs_inline`, `colon_fence`, `deflist`, `substitution`. + +### File Structure + +- Content pages are referenced once via their section landing page. +- Landing pages in `docs/how-to/`, `docs/tutorial/`, and related sections organize navigation. +- Images are stored in `docs/
/images/` directories. +- Shared links are defined in `docs/reuse/links.txt` and auto-included via `rst_epilog`. + +## Critical Patterns + +### Redirects + +When renaming/moving/deleting files, **always add redirects**: + +**Add redirects in `docs/conf.py` under `redirects = {}`**: + +```python +redirects = { + # Internal redirect (full docs path) + "how-to/old-page": "how-to/new-page", + # External redirect (full URL) + "how-to/obsolete-page": "https://example.com/new-location", +} +``` + +### Custom Wordlist + +Add valid technical terms/acronyms to `docs/.custom_wordlist.txt` (alphabetically sorted) rather than wrapping in backticks, unless you want monospaced rendering. + +### PR Requirements + +- Link PRs to issues with `Fixes #` in the description. +- Use [Conventional Comments](https://conventionalcomments.org/) for feedback. +- Include manual testing for documentation workflows and commands. +- Preview builds are available via the Read the Docs check on the PR. + +## Common Tasks + +### Meta Description Format + +All pages must have an HTML meta description. The format depends on file type: + +**MyST Markdown** (`.md`): Add to the front matter at the top of the file: + +```yaml +--- +myst: + html_meta: + description: "Brief, user-facing description of the page content (50-160 characters)." +--- +``` + +**reStructuredText** (`.rst`): Add as a directive at the top of the file before the first heading: + +```rst +.. meta:: + :description: Brief, user-facing description of the page content (50-160 characters). +``` + +Metadata descriptions help with search results and accessibility. Keep them concise and action-oriented. + +### Adding New Content + +1. Determine Diátaxis category (tutorial/how-to/explanation/reference) +2. Create `.md` / `.rst` file in appropriate subdirectory +3. Add or review the page meta description (see [Meta Description Format](#meta-description-format) above): + + - New files: must include a meta description + - Existing files: add one if missing, otherwise review and update it if it no longer matches the page intent + +4. Add to corresponding `index.rst` / `index.md` or section landing page +5. Use section-prefixed labels / targets for cross-references in both MyST and RST + For example `(how-to-topic-name)=` in MyST or `.. _how-to-topic-name:` in RST +6. Test: `make run` and verify navigation, formatting, and cross-references work as expected +7. Run quality checks before committing: + + ```bash + make spelling + make linkcheck + make lint-md + make vale + make html + ``` + + Fix any warnings or errors reported by these commands. +8. Submit PR with clear description and link to any related issues + +Use short section prefixes for anchors when naming labels, for example `tutorial-*`, `how-to-*`, `exp-*`, and `ref-*`. + +### Updating Links + +- Prefer reputable sources (official upstream documentation, not blog posts). +- Use "Related topics" sections for supplementary links at the end of the page. +- The first package mention should link to documentation or manpages. + +### Handling Errors + +- **Spelling errors**: Add to `docs/.custom_wordlist.txt` or wrap in backticks. +- **Link errors**: Check `linkcheck_ignore` in `docs/conf.py`. +- **Build errors**: Check `docs/.sphinx/venv/pip_install.log` for dependency issues. +- **Sphinx warnings**: Run `make html` and resolve missing references, syntax issues, and other warnings before merge. + +## Don't Do This + +- Don't use emojis in documentation. +- Don't skip heading levels in document structure. +- Don't assume reader knowledge without brief explanations or links. +- Don't link to blog posts when official docs exist. +- Don't treat this repository as a mixed code-and-docs project. diff --git a/.github/skills/documentation-build/SKILL.md b/.github/skills/documentation-build/SKILL.md new file mode 100644 index 0000000..72b0a9f --- /dev/null +++ b/.github/skills/documentation-build/SKILL.md @@ -0,0 +1,98 @@ +--- +name: documentation-build +description: "Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues." +--- + +# Documentation Build Validation + +## Scope + +Build validation only: detect documentation build configuration, run applicable build targets, collect all errors and warnings, and categorize by severity. + +## Inputs + +- Repository root. + +## Actions + +1. **Identify documentation root**: Detect docs roots in this order: + + - `docs/` + - Repository root, when both `conf.py` and `Makefile` exist + - `doc/` + - `documentation/` + - `site/` + - `docs-src/` + + If still not found, perform a bounded search for `conf.py` (max depth 4) and use its parent as the docs root. + +2. **Detect build configuration**: Check for the presence of: + + - `conf.py` in the detected docs root + - `Makefile` in the detected docs root + - Optional: `.readthedocs.yaml` in the detected docs root or at repository root + + If Sphinx build artifacts are absent in the target repository, report "not applicable" in findings and exit cleanly. + +3. **Run build targets** (when applicable): + + ```bash + cd + # Use clean-doc when available, otherwise fall back to clean + if make -n clean-doc 2>/dev/null; then + make clean-doc + else + make clean + fi + make html + ``` + + Run additional checks for targets that exist. + Check each target before running to avoid false failures: + + ```bash + # Check and run each target if available + for target in spelling linkcheck lint-md vale woke pa11y; do + if make -n $target 2>/dev/null; then + make $target + fi + done + ``` + +4. **Capture output and handle failures**: If any command fails: + + 1. Capture the full error output from stderr and stdout + 2. Run `make clean-doc` (or `make clean` if `clean-doc` is unavailable) to reset build state + 3. Retry the failed build command once + 4. If retry fails, STOP and report all captured errors + 5. Do not proceed to content analysis until build succeeds + + Warnings must be collected and reported, but are not blocking unless the repository explicitly treats warnings as errors. + +5. **Categorize findings by severity**: + + - **Errors**: Build failures, broken links, missing files. + - **Warnings**: Deprecation notices, missing references, formatting issues. + - **Info**: Suggestions, minor notices. + +6. **Verify completion**: Confirm the validation completed: + + - Build targets were executed (or determined not applicable) + - Output was captured (errors and warnings) + - Findings were categorized by severity + + State the completion status: + - `✓ Build validation complete: [N] errors, [M] warnings found` + - OR `✓ Build validation complete: No issues found` + - OR `✓ Build validation: Not applicable - Sphinx artifacts not detected` + +## Constraints + +- Do not approve documentation that fails the Sphinx build. +- Build docs locally to catch build warnings. +- Do not invent Makefile targets; only use targets confirmed to exist in the target repository. + +## Output + +A build validation report listing all errors and warnings, categorized by severity. +If Sphinx artifacts are not detected, report "Not applicable -- Sphinx artifacts not detected in target repo". diff --git a/.github/skills/documentation-diataxis/SKILL.md b/.github/skills/documentation-diataxis/SKILL.md new file mode 100644 index 0000000..4118aa3 --- /dev/null +++ b/.github/skills/documentation-diataxis/SKILL.md @@ -0,0 +1,131 @@ +--- +name: documentation-diataxis +description: "Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content." +--- + +# Diataxis Classification Review + +## Scope + +Diataxis classification only: identify whether each page is a tutorial, how-to guide, explanation, or reference; note structural mismatches between content type and declared category, and suggest improvements where real issues exist. +Ground classification in the Diataxis foundations: the two axes of craft (action vs cognition, acquisition vs application) define four user needs (learning, goals, information, understanding). +This skill identifies flaws and provides actionable recommendations; it does not enforce compliance or apply pass/fail criteria. + +## Inputs + +- Documentation file(s) under review. +- Diataxis framework principles (embedded in classification criteria below). + +## Actions + +1. **Identify intended category**: Determine the declared category based on directory location (`tutorial/`, `how-to/`, `explanation/`, `reference/`) and file metadata (front matter keys such as `category`, `type`, `diataxis`, or reST `.. meta::` entries). + +2. **Infer actual category**: Analyze the text's structure, tone, and progression to determine which quadrant it actually resembles. + Use these classification criteria: + + - **Tutorial indicators**: + - Step-by-step progression building a complete project + - Imperative mood ("Create a file", "Run this command") + - Learning-focused language ("you will learn", "by the end") + - Safe, controlled environment (specific versions, no branching) + - Frequent reassurance and checkpoints + - Teaches by doing, not explaining + + - **How-to guide indicators**: + - Problem-solution format with clear goal + - Assumes existing knowledge and competence + - Clearly states prerequisites and applicability scope + - Action-oriented ("To achieve X, do Y") + - Flexible, allows for variation + - Focuses on results, not learning + - Omits explanations unless critical to success + + - **Reference indicators**: + - Descriptive, declarative statements + - Comprehensive coverage of subject + - Neutral, technical tone + - Structured for lookup (tables, lists, alphabetical) + - Parameters, options, API signatures + - Accuracy over narrative + + - **Explanation indicators**: + - Conceptual focus ("why" and "how it works") + - Discursive, exploratory tone + - Comparative analysis + - Context, background, relationships + - Illuminates understanding, not action + - May include history, design decisions, alternatives + - May contain subjective opinions and personal perspectives + +3. **Check user need alignment**: + + Map the page to the user need implied by the action/cognition and acquisition/application axes (learning, goals, information, understanding). + + - **Tutorials**: Is it a learning-oriented lesson? + Does it build confidence through doing? Is it linear and safe? + - **How-to guides**: Is it a task-oriented recipe? + Does it help a competent user solve a specific problem? + Is it goal-focused? + - **Reference**: Is it information-oriented? + Does it describe things accurately and completely? + Is it structured for lookup? + - **Explanation**: Is it understanding-oriented? + Does it clarify concepts, context, and relationships? + Is it discursive? + +4. **Note hard-to-fit genres**: Some documentation types do not align cleanly with a single quadrant (for example, release notes or contributing guides). + Flag these cases explicitly, reference the Diataxis guidance on complex hierarchies (https://diataxis.fr/complex-hierarchies/), and choose the closest fit category for reporting. + +5. **Evaluate quality**: + + - **Functional quality**: Is the content accurate, complete, consistent, useful, and precise? + - Missing prerequisites or dependencies + - Incomplete steps or procedures + - Inconsistent terminology or naming + - Outdated information (version mismatches, deprecated features) + + - **Deep quality**: Does the content have good flow? + Does it anticipate user questions? + Is the cognitive load appropriate? Is the experience clear? + - Paragraph length (>4 sentences may suggest need for breaking) + - Sentence complexity (nested clauses, dense jargon) + - Transition quality (abrupt topic changes, missing connectives) + - Progressive disclosure (introducing too much too soon) + - User journey mapping (gaps in expected flow) + +6. **Document misalignments**: Explicitly identify where the document fails to meet the needs of its category, jumps between categories, or where quality breaks down. + For each issue, provide: + - Specific location (section, paragraph) + - Nature of the problem + - Impact on user experience + - Concrete suggestion for improvement + +7. **Verify completion**: Confirm the analysis completed: + + - Category classification completed (declared vs inferred) + - User need alignment analyzed + - Quality assessment performed (functional and deep quality) + - Misalignments documented with recommendations + + State the completion status: + - `✓ Diataxis analysis complete: [declared category] → [inferred category], [N] issues found` + - OR `✓ Diataxis analysis complete: Content aligns well with [category]` + +## Constraints + +- Do not ignore the Diataxis framework. +- Assign each page to exactly one quadrant. +- Do not introduce categories beyond the four quadrants. + +## Output + +A Diataxis Analysis Report detailing: + +- Declared category (from metadata/directory structure). +- Inferred category (from content analysis). +- User need alignment analysis (which quadrant best serves the user). +- Functional quality findings (with specific examples). +- Deep quality findings (with specific examples). +- Identified issues and actionable recommendations for improvement. + +If no significant issues are found, state that the documentation aligns well with its intended category. diff --git a/.github/skills/documentation-review/SKILL.md b/.github/skills/documentation-review/SKILL.md new file mode 100644 index 0000000..0b93741 --- /dev/null +++ b/.github/skills/documentation-review/SKILL.md @@ -0,0 +1,192 @@ +--- +name: documentation-review +description: "Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality." +--- + +# Documentation Review + +## Scope + +Orchestration only: defines the end-to-end review workflow, specifies the order in which atomic skills are invoked, and renders the final consolidated report using the report template at `references/doc-review-report-template.md`. +This orchestration must support docs-only repositories where documentation content and documentation tooling are the primary verification scope. + +## Persona + +You are a technical documentation reviewer and editor for the project. +Your job is to ensure the documentation is clear, accurate, consistent with code, and follows the project's style guide. +You apply the Diataxis framework (Tutorial, How-to, Explanation, Reference) rigorously. + +## Workflow + +Follow these stages sequentially. **Do not skip stages.** + +### Execution Requirements + +**CRITICAL:** After completing each stage, you MUST: +1. Confirm the skill was actually invoked (not just described) +2. Capture the output and record findings +3. State the completion status explicitly + +**Verification Pattern:** +After each stage, state: +- `✓ Stage [N] complete: [skill-name] generated [N] findings` +- If no findings: `✓ Stage [N] complete: [skill-name] found no issues` + +**Do NOT proceed to Stage [N+1] until Stage [N] is verified complete.** + +--- + +### Stage 1: Build Validation + +**Execute:** Use the `documentation-build` skill to validate the documentation build. + +**Capture:** Record all build errors and warnings. + +**Verify:** Confirm build status (pass/fail) before proceeding. + +**Decision Point:** If the build fails, report build issues immediately and STOP. Do not proceed to content analysis until the documentation builds without errors. + +**Checkpoint:** `✓ Stage 1 complete: documentation-build [passed/failed with N errors]` + +--- + +### Stage 2: Documentation Structure Discovery + +**Execute:** Map the documentation structure before analyzing content. + +**Actions:** +1. Detect and list all documentation files under the docs root (`docs/` first; use repository root only when `conf.py` and `Makefile` are at repository root, otherwise use `docs/` or equivalent). +2. Identify the documentation build system (Sphinx, MkDocs, Jekyll, etc.) +3. Note the directory structure (flat vs. categorized) +4. Record any metadata patterns (frontmatter, sidebar configs) + +**Output:** Store this structural map internally for use in later stages. + +**Checkpoint:** Confirm you have identified: +- [ ] Documentation root directory +- [ ] Build system type +- [ ] File organization pattern +- [ ] Metadata conventions (if any) + +Then state: `✓ Stage 2 complete: Structure mapped ([N] files in [system] with [pattern] organization)` + +--- + +### Stage 3: Diataxis Classification + +**Execute:** Use the `documentation-diataxis` skill to analyze each documentation page. + +**Capture:** Record the declared category (from metadata/directory) and inferred category (from content analysis) for each page. + +**Verify:** Confirm you have classification results for all documentation pages analyzed. + +**Checkpoint:** `✓ Stage 3 complete: documentation-diataxis analyzed [N] pages, found [N] misalignments` + +--- + +### Stage 4: Structure Audit + +**Execute:** Use the `documentation-structure` skill to validate documentation organization. + +**Input Required:** Use the Diataxis classification output from Stage 3 to validate directory placement. + +**Capture:** Record all structural violations (file naming, metadata, directory placement, navigation, cross-references). + +**Verify:** Confirm structural audit completed for all pages. + +**Checkpoint:** `✓ Stage 4 complete: documentation-structure found [N] violations` OR `✓ Stage 4 complete: documentation-structure found no violations` + +--- + +### Stage 5: Accuracy Verification + +**Execute:** Use the `documentation-verify` skill to cross-reference documentation claims against repository evidence. + +For docs-only repositories, validate claims against documentation tooling and artifacts in the same repository (for example, `conf.py`, `Makefile`, Sphinx configuration, redirects, and documentation examples). + +**Capture:** Record all accuracy findings grouped by classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive). + +**Verify:** Confirm repository-evidence verification completed for all claims in changed documentation. + +**Checkpoint:** `✓ Stage 5 complete: documentation-verify found [N] accuracy issues` OR `✓ Stage 5 complete: documentation-verify found no accuracy issues` + +--- + +### Stage 6: Style Review + +**Execute:** Use the `documentation-style` skill to evaluate documentation against the project style guide. + +**Capture:** Record all style violations with quoted passages from the style guide. + +**Verify:** Confirm style review completed for all documentation. + +**Checkpoint:** `✓ Stage 6 complete: documentation-style found [N] style violations` OR `✓ Stage 6 complete: documentation-style found no style violations` + +--- + +### Stage 7: Consolidated Report + +**Execute:** Synthesize findings from all stages into a structured, actionable review using the report template at `references/doc-review-report-template.md`. + +**Assembly Instructions:** + +For each skill output, extract findings and populate the corresponding report section: + +| Skill | Report Section | Format | +|-------|----------------|--------| +| documentation-build | Build Findings | List of errors/warnings or "No issues found" | +| documentation-verify | Accuracy Findings | Grouped by classification (unsupported/outdated/incorrect/imprecise) | +| documentation-diataxis | Diataxis Findings | Table of declared vs inferred categories, list misalignments | +| documentation-structure | Structure Findings | List of violations or "No issues found" | +| documentation-style | Style Findings | List of violations with quoted style guide passages | + +**Handling Empty Results:** +- If a skill produces no findings: Write "No issues found" in that section +- If a skill is not applicable: Write "Not applicable - [reason]" (e.g., "Not applicable -- Sphinx artifacts not detected") + +**Priority Order:** Present findings in priority order (highest priority first): + +1. **Build Findings (BLOCKING)** - Must be resolved before content analysis +2. **Accuracy Findings (CRITICAL)** - Code-documentation mismatches +3. **Diataxis Findings (HIGH)** - Category misalignments affecting usability +4. **Structure Findings (MEDIUM)** - Organizational and navigation issues +5. **Style Findings (LOW)** - Style guide compliance + +**Checkpoint:** `✓ Stage 7 complete: Consolidated report generated with findings from [N] stages` + +--- + +## Error Handling + +If a stage fails to complete, handle as follows: + +### Build Validation Failure +- Report build errors immediately +- STOP the workflow - do not proceed to content analysis +- Include build errors in the final report + +### Skill Invocation Errors +- Report the error in the corresponding report section +- Continue with remaining stages +- Note the failure in the Summary section + +### Missing Dependencies +- Report what's missing (for example, "Style guide not found at references/doc-style-guide.md") +- Mark that stage as "Incomplete" in the report +- Continue with other stages + +### Incomplete Stages +If any stage could not be completed, add an "Incomplete Stages" section to the report listing: +- Which stage failed +- Why it failed +- What's needed to complete it + +--- + +## Constraints + +- Provide criticism and suggestions rather than direct bulk rewrites. +- Do not modify source code to fix documentation without explicit request. +- Before restructuring large documentation sections (for example, moving files between tutorial and how-to), ask first. +- Before suggesting new coverage entities, categories, or metadata patterns, ask first. +- If code examples seem correct but do not match your understanding of the codebase, ask first. diff --git a/.github/skills/documentation-review/references/doc-review-report-template.md b/.github/skills/documentation-review/references/doc-review-report-template.md new file mode 100644 index 0000000..ff60cc3 --- /dev/null +++ b/.github/skills/documentation-review/references/doc-review-report-template.md @@ -0,0 +1,68 @@ +## Documentation Review Report + +**Reviewed:** + +**Date:** + +**Skills Applied:** + +--- + +### Build Findings (BLOCKING) + +*Source: documentation-build* + + + +--- + +### Accuracy Findings (CRITICAL) + +*Source: documentation-verify* + + + +--- + +### Diataxis Findings (HIGH) + +*Source: documentation-diataxis* + + + +--- + +### Structure Findings (MEDIUM) + +*Source: documentation-structure* + + + +--- + +### Style Findings (LOW) + +*Source: documentation-style* + + + +--- + +### Incomplete Stages + +*Only include this section if any stage failed to complete* + + + +--- + +### Summary + + + +**Recommended Action Priority:** +1. Resolve blocking build issues first +2. Fix critical accuracy/code-backing issues +3. Address high-priority Diataxis misalignments +4. Resolve structural issues +5. Apply style corrections diff --git a/.github/skills/documentation-structure/SKILL.md b/.github/skills/documentation-structure/SKILL.md new file mode 100644 index 0000000..258a265 --- /dev/null +++ b/.github/skills/documentation-structure/SKILL.md @@ -0,0 +1,66 @@ +--- +name: documentation-structure +description: "Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure." +--- + +# Documentation Structure Audit + +## Scope + +Document structure only: heading hierarchy, section ordering, presence of required sections (introduction, prerequisites, steps, reference), file naming, metadata blocks, navigation, and cross-references. + +## Inputs + +- Documentation file(s) under review. +- Documentation directory structure. +- Diataxis classification output (from the `documentation-diataxis` skill, when run as part of the orchestrated review). + +## Actions + +1. **File Naming**: + + Verify files use lowercase with dashes and the correct extension for their syntax (for example, `connect-vscode.rst` for reST, `connect-vscode.md` for MyST). + +2. **Metadata**: + + Ensure every page has required metadata near the top when the repository's docs conventions require it: `.. meta::` after the anchor label for reST, or the MyST equivalent (front matter or `meta` directive) for Markdown sources. + +3. **Directory Placement**: + + Confirm the file is located in the directory matching its intended Diataxis category (for example, tutorials in `tutorial/`, how-to guides in `how-to/`). + +4. **Navigation**: + + Ensure new pages are added to the `toctree`. + +5. **Cross-References**: + + - Prefer native internal cross-reference roles (`:ref:`, `:doc:`, `{ref}`, `{doc}`, `{numref}`) over plain relative page links. + - Flag unresolved or brittle cross-references, not valid uses of `:doc:`/`{doc}`. + - Suggest adding links to improve documentation discoverability. + - Verify cross-references resolve correctly. + +6. **Verification**: + + Confirm the structural audit completed: + + - File naming checked for all files + - Metadata presence verified + - Directory placement validated (using Diataxis classification if available) + - Navigation structure checked (toctree entries) + - Cross-references validated + + State the completion status: + - `✓ Structure audit complete: [N] violations found` + - OR `✓ Structure audit complete: No violations found` + +## Constraints + +- Do not modify files during the audit; this is a read-only review. +- Do not invent metadata requirements; check against repository's documented conventions. +- Focus on structural issues only; do not flag style preferences. +- When Diataxis classification is available (from orchestrated review), use it to validate directory placement. Otherwise, infer from directory name. + +## Output + +A list of structural or metadata violations covering file naming, metadata, directory placement, navigation, and cross-reference issues. diff --git a/.github/skills/documentation-style/SKILL.md b/.github/skills/documentation-style/SKILL.md new file mode 100644 index 0000000..74ad283 --- /dev/null +++ b/.github/skills/documentation-style/SKILL.md @@ -0,0 +1,60 @@ +--- +name: documentation-style +description: "Enforces project documentation style guide compliance for tone, voice, terminology, punctuation, and formatting. Use when checking documentation style or validating MyST/reST syntax. Cites specific style guide violations." +--- + +# Documentation Style Review + +## Scope + +Style conformance only: tone, voice, terminology, punctuation, Oxford comma, active versus passive voice, prohibited phrases, and formatting conventions. + +## Inputs + +- Documentation file(s) under review. +- Normative style asset: `references/doc-style-guide.md`. +- Syntax-specific style guides (fetched at runtime): + - MyST: `https://raw.githubusercontent.com/canonical/sphinx-stack-docs/refs/heads/main/docs/reference/myst-syntax.md` + - reST: `https://raw.githubusercontent.com/canonical/sphinx-stack-docs/refs/heads/main/docs/reference/rst-syntax.rst` + +## Actions + +1. **Load style guides**: Read `references/doc-style-guide.md`. + Fetch the syntax-specific guide matching the file type (MyST for `.md`, reST for `.rst`). + +2. **Syntax compliance**: Check headings, lists, code blocks, inline literals, and directives against the applicable syntax guide. + Treat every instruction in the guide as mandatory; do not rely on a subset of rules. + +3. **Full style guide compliance**: Read and apply all rules defined in `references/doc-style-guide.md`. + Treat every instruction in the guide as mandatory; do not rely on a subset of rules. + +4. **Style guide citation**: For every violation found, locate and quote the specific passage in `references/doc-style-guide.md` or the syntax-specific guide that supports the finding. + +5. **Fallback behavior**: If syntax guides cannot be fetched (offline or network blocked), continue the review using `references/doc-style-guide.md` and the syntax patterns already present in the documentation set. + + If `references/doc-style-guide.md` is unavailable, STOP the review and report that the style guide cannot be accessed. + +6. **Verification**: + + Confirm the style review completed: + + - Style guides loaded (doc-style-guide.md and syntax-specific guide if available) + - Syntax compliance checked against applicable guide + - Style guide compliance checked against all rules in doc-style-guide.md + - All violations cited with quoted passages from style guides + + State the completion status: + - `✓ Style review complete: [N] violations found` + - OR `✓ Style review complete: No violations found` + +## Constraints + +- Quote style guides when making style suggestions. +- Do not suggest style or markup changes without quoting the style guides. + +## Output + +A list of style violations, each accompanied by: + +- The specific passage quoted from the style guide or syntax reference. +- The observation or suggested change. diff --git a/.github/skills/documentation-style/references/doc-style-guide.md b/.github/skills/documentation-style/references/doc-style-guide.md new file mode 100644 index 0000000..53bbde3 --- /dev/null +++ b/.github/skills/documentation-style/references/doc-style-guide.md @@ -0,0 +1,649 @@ +```{eval-rst} +:orphan: + +.. meta:: + :description: Documentation style guide covering file naming, + structure, semantic line breaks, reStructuredText and Markdown + conventions, terminology, and project-specific patterns. +``` + + + +# Documentation style guide + +This style guide documents the established conventions used in the project documentation. It captures actual patterns observed across the documentation set and serves as a reference for maintaining consistency in new contributions. + +This guide is subordinate to your organization's documentation standards but records project-specific decisions and patterns that extend or clarify those standards. + +--- + +## File naming and organization + +**Directory structure** + +The documentation follows the [Diátaxis](https://diataxis.fr/) framework with four main sections: + +``` +. +└── docs/ + ├── tutorial/ # Step-by-step learning paths + ├── how-to/ # Task-oriented guides + ├── explanation/ # Conceptual information + ├── reference/ # Technical specifications + ├── reuse/ # Shared links and reusable snippets + ├── conf.py # Sphinx configuration + └── Makefile # Docs build and validation targets +``` + +**File naming convention** + +All filenames use lowercase letters and dashes for word separation. + +Examples: + +- Good: `part-1-get-started.rst` +- Good: `connect-editor.rst` +- Good: `network-interface.rst` +- Good: `container-vs-dockerfile.rst` +- Avoid: `ConnectEditor.rst` (uppercase) +- Avoid: `network_interface.rst` (underscore) + +Optional: Tutorial files may use a sequential numbering pattern: + +``` +part-1-get-started.rst +part-2-work-with-features.rst +part-3-advanced-concepts.rst +part-4-production-deployment.rst +``` + +How-to files: Use verb-first naming pattern: + +``` +add-configuration.rst +connect-editor.rst +forward-ports.rst +debug-issues.rst +resolve-conflicts.rst +``` + +Explanation files use noun-based naming: + +``` +concepts.rst +interface-concepts.rst +best-practices.rst +runtime-behavior.rst +``` + +Reference files match command structure: + +``` +command-launch.rst +command-connect.rst +build-tool.md +``` + +Filenames and directory names in the documentation repo should be in lowercase, +with dashes instead of spaces; the directory tree must be built in a way that +provides for readable, meaningful URLs: `/how-to/change-tyres`. + +--- + +## Page structure and metadata + +**Standard page structure** + +Every documentation page follows a consistent structure: +anchor label, metadata block, page title, opening paragraph, and section hierarchy. +Use the syntax references for exact markup and placement details. + +**Metadata block** + +Every page must include a metadata description near the top of the file. +For MyST, use front matter metadata. +For reStructuredText, use `.. meta::`. +Use a brief, clear description (typically 1-2 lines, within 160 characters), +wrapping at natural phrase boundaries. + +**Anchor labels** + +Use lowercase with underscores or dashes. + +Optional: Prefix labels with section type. +Use prefixes consistently across the docs. + +Prefixes: + +- `tutorial-` - Tutorial sections +- `how-to-` - How-to guides +- `exp-` - Explanation articles +- `ref-` - Reference documentation + +Examples: `tutorial-get-started`, `how-to-add-actions`, `exp-interface-concepts`, `ref-command-launch`. + +--- + +## Writing style and tone + +**Voice and audience** + +Target audience is developers and technical professionals seeking to: + +* Achieve specific goals without much overhead and roundabout musings +* Perform and conceive complex ad-hoc tasks and workflows that require precision and depth +* Attain understanding of the project's key capabilities beneficial for their scenarios + +Content follows the Diátaxis framework, providing: + +* Concise tutorials for common, starter-level actions and scenarios, eliminating the need to invent custom steps and allowing novice users to journey along the hot path effortlessly +* Elaborate explanations of the thinking behind the project's design, including design decisions, related concepts, and how it should be used +* Detailed how-to guides that address specific needs of advanced users and cover topics beyond basic entry-level operations +* Comprehensive reference of all options, settings, and details available to customize the project's operation in any desirable manner + +The tone is authoritative but relaxed, confident but approachable. Think water cooler conversation, not classroom session. + +Example: + +```text + is a tool for defining and handling development environments. + +List your dependencies and components in YAML to define an environment. The key pieces of a definition are components, independent but connectable units of functionality. The project simplifies experiments with your environment layout. +``` + +**Active and passive voice** + +Use active voice for user actions and cause-effect relationships. Use passive voice when the agent is unknown or the effect is the focus. + +Active voice examples (preferred for actions): +- "The server hosts all files" +- "You install apps with the App Center" +- "The validate library checks the form for errors" + +Passive voice examples (appropriate for effects): +- "Before upload, the form is checked for errors" +- "The files are deleted every time the script runs" + +Pattern recognition: Passive voice uses `is/are/was/were/been/being + past participle` (e.g., "is installed", "are checked"). + +**Direct instructions** + +Use imperative mood for instructions. Avoid "you can" or "you may" for required actions. + +Preferred: + +``` +Install the application using the `--classic` option: +``` + +Avoid: + +``` +You can install the application with: +``` + +**Paragraph length** + +Keep paragraphs focused and relatively short (2-5 sentences typically). Complex topics should be broken into multiple paragraphs. + +Example: + +```restructuredtext +Install the project, +upgrading the prerequisites if needed, +then ensure it runs. + +Authenticate to the package manager and install +using the required options: +``` + +**Paragraph structure (optional)** + +Where suitable, structure paragraphs using the Topic-Development-Example-Summary (TDES) pattern: + +1. **Topic**: Open with a clear statement of what the paragraph addresses +2. **Development**: Explain the concept or provide necessary context +3. **Example**: Illustrate with a concrete example +4. **Summary**: Close with the key takeaway or implication + +This pattern is particularly effective for explanatory content but should be applied flexibly; not every paragraph requires all four elements. + +Example applying TDES: + +```text +Interfaces enable communication between components and the host system. +Each interface defines a specific capability, such as network access or GPU usage. +For instance, the `network` interface allows a component to access external services, +while the `gpu` interface provides access to hardware acceleration. +Using interfaces, you can precisely control what resources each component can access. +``` + +In practice, simpler paragraphs may use just Topic-Example or Topic-Development, depending on the content's purpose and complexity. + +**Clarity over cleverness** + +- State prerequisites explicitly +- Define terms at first use +- Avoid assumptions about reader knowledge +- Use precise, unambiguous language + +**Words and phrases to avoid** + +Avoid clichés, violent metaphors, and jargon. Replace them with simpler alternatives: + +- **Clichés** + - `the ability to`, `is able to` → `can` + - `in order to` → `to` + - Avoid: `allow`, `going forward`, `not only...but also` + +- **Violent metaphors** + - `kill`, `terminate` → `stop` + - `execute` → `run` + - `eliminate` → `remove` + +- **Jargon** + - `leverage` → `use` + - `end user` → `user` + - `use case` → `example` or `scenario` + - Avoid: `ecosystem`, `form factor`, `harness`, `next level` + +This is not an exhaustive list; use your best judgment. + +**Latin words and phrases** + +Replace Latin phrases with English equivalents: + +- `e.g.` → `for example`, `such as` +- `i.e.` → `that is`, `in other words` +- `etc.` → `and so on` +- `via` → `through`, `with`, `using` +- `ad hoc` → `unscheduled`, `temporary`, `bespoke` +- `per se` → `necessarily`, `intrinsically` +- `versus`, `vs.` → `compared to`, `opposed to` +- `vice versa` → `the reverse`, `the other way around` +- `circa` → `around`, `near` +- `cf.` → `refer to` + +This is not an exhaustive list; use your best judgment. + +**Demonstrative pronouns** + +Avoid orphan "this", "these", "those", "that" when ambiguous. Pair with the noun for clarity. + +Good: "The `yaml` object is sourced from the `yamllib` library. This object is only available if..." + +Avoid: "The `yaml` object is sourced from the `yamllib` library. This is only available if..." (unclear if referring to object or library) + +**Language and spelling** + +Convention: Use US English spelling, grammar, and formatting conventions throughout the documentation. + +Common US/UK differences: +- Patterns: `-ize` (not `-ise`), `-or` (not `-our`), `-able` (not `-eable`) +- US: `license` (noun and verb), `defense`, `program`, `percent`, `skeptical`, `catalog`, `traveling`, `labeled` +- UK: `licence` (noun), `defence`, `programme` (non-IT), `per cent`, `sceptical`, `catalogue`, `travelling`, `labelled` + +Common technology terms: +- `email`, `online`, `website`, `internet` +- `setup` (noun), `set up` (verb) +- `backup` (noun), `back up` (verb) +- `login` (noun), `log in` (verb) +- `space-separated`, `comma-delimited` +- `open source` (noun), `open-source` (adjective) + +Examples: +- Good: `color`, `center`, `analyze`, `behavior` +- Avoid: `colour`, `centre`, `analyse`, `behaviour` +- Good: Use serial comma: "components, interfaces, and environments" +- Good: Double quotes for quotations: "The project is a tool" + +**Contractions** + +Acceptable: `aren't`, `can't`, `couldn't`, `didn't`, `doesn't`, `don't`, `hadn't`, `hasn't`, `haven't`, `isn't`, `it's`, `mustn't`, `wasn't`, `won't`, `wouldn't`, `you're`, `you've`, `you'll`, `we're`, `we've` + +Forbidden: `ain't` (colloquial), `gonna`, `gotta`, `something's` (confusion with possessive), `I'd`, `I'll` (avoid first person) + +**Dates and numbers** + +Date format: +- Single day: `1 January 2013` +- Range within month: `1-2 January 2013` +- Range across months: `1 January - 2 February 2013` + +Numbers: +- Spell out below 10: `seven servers` +- Use digits from 10 onwards: `15 containers` +- Exception: Always use digits for units of measurement: `5 GB`, `3 seconds` +- Use commas for thousands: `7,000` not `7000` + +--- + +## Semantic line breaks (optional) + +**Pattern** + +The documentation consistently uses semantic line breaks (one line per clause or significant phrase) in reStructuredText files. This improves version control diffs and editing precision. + +Rationale: Semantic breaks make git diffs more readable and help reviewers identify exactly what changed in a sentence or paragraph. + +**Implementation** + +Break lines at natural semantic boundaries: +- After each complete clause +- Before coordinating conjunctions (and, but, or) +- Before relative clauses (which, that, who) +- After introductory phrases + +Example: + +```restructuredtext +This is the first section of the :ref:`four-part series `; +a practical introduction +that takes you on a tour +of the essential |project_markup| activities. +``` + +MyST equivalent: + +````markdown +This is the first section of the {ref}`four-part series `; +a practical introduction +that takes you on a tour +of the essential |project_markup| activities. +```` + +**When to break** + +Break after: +- Complete independent clauses +- Introductory prepositional phrases +- Transitional phrases +- Items in a complex series + +Keep together: +- Short phrases that form a single unit +- Inline markup and its target word +- Cross-reference markup + +Example: + +```restructuredtext +Interfaces are a mechanism for communication and resource sharing. +It is an integral part of environment isolation, +ensuring that each environment operates in its own isolated context, +while still allowing controlled interactions among the components and with the host. +``` + +--- + +## Headings and titles + +**Capitalization** + +Pattern: Sentence case for all headings (capitalize only first word and proper nouns). + +Exception: Product names and proper nouns maintain their capitalization. + +**Heading constraints** + +- Headings must not end with a period +- Avoid links in headings +- Use `code` styling sparingly in headings (only when essential, such as command references) +- Headings must not be followed directly by a subheading (provide introductory content) +- Do not skip heading levels (e.g., h1 followed by h3) + +**How-to title pattern** + +How-to guides follow the pattern: "How to [action] [object]" and use imperatives, not gerunds: +- Good: "How to create an instance" (imperative) +- Avoid: "How to creating an instance" or "Creating an instance" (gerund) +- How to forward ports with tunneling +- How to fix connection conflicts +- How to debug issues in environments + +Linking exception: In navigation and links, drop "How to" prefix and use infinitive: + +```restructuredtext +How-to guides: + +* Debug issues in environments +* Connect IDE to an environment +``` + +--- + +## Markup and formatting policies + +Use the syntax references for markup details. +Apply the policies below for project-specific conventions. + +**Admonition placement:** Place admonitions at the end of the subsection they relate to, rather than interrupting the flow of text in the middle of a section. This is especially relevant for multiple admonitions per section. + +**Inline markup** + +Semantic markup preference: Use semantic markup roles (for example, sample values, environment variables, file paths, commands, GUI labels, and programs) instead of generic emphasis. Choose the most specific role that suits the purpose and use it consistently. + +Use italics sparingly to introduce new terms and for emphasis. Leave bold for product names and commands. + +Commands in command roles should be presented in their complete form and should not be used as verbs or nouns in the text. +Use non-breaking spaces to prevent longer compound commands from wrapping. + +End directory path names with a slash where possible and conventional to disambiguate directories from files. + +Format placeholders in uppercase within angle brackets, without underscores. + +**Non-breaking spaces:** Use non-breaking spaces for important proper names and compound commands where line breaks would be awkward. + +**"See also" sections (optional)** + +"See also" sections can appear on pages under any pillar and link to related content not immediately essential but potentially useful. Break link lists down by pillar, listing pillars and individual subsections in alphabetical order. + +**Tab headings** + +Pattern: Keep tab headings noun-based and consistent across related content. Avoid unintended "sticky toggling" (where tab state persists inappropriately across different contexts). + +**Sphinx extensions and roles** + +Preference: Use Sphinx-specific [roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) and [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) over `docutils` generic equivalents. Use all their options and capabilities, listing options in alphabetical order. + +**Spacing and formatting** + +Section gaps: Include a non-cumulative two-line gap (two blank lines) after code samples, lists, tables, and before headings for visual clarity. + +--- + +**Simplified markup for GitHub** + +Use simplified markup for files that have special meaning on GitHub and need to be rendered there (such as `README.md`, `CONTRIBUTING.rst`, `SECURITY.rst`). For example, don't use `$` prompts in command samples for these files because GitHub doesn't prevent their selection during copying, which can confuse users. + +--- + +**Command prompts and code blocks** + +**DO NOT** use `$` or `#` prompts in code samples except when using the `console` lexer, which makes them non-selectable. Prompts cause problems for users who copy-paste code. + +It is ONLY acceptable to use the `$` prompt when it's non-selectable. The `console` lexer in `.. code-block::` automatically handles this, making the prompt non-selectable during copy operations. + +**Avoid inline comments** in bash code blocks. Use prose before, after, or between code blocks instead: + +Avoid: + +```bash +juju deploy wordpress +juju deploy ntp-master --to 2 # colocates with wordpress +``` + +Preferred: + +``` +Deploy wordpress, then colocate ntp-master with it: +``` + +```bash +juju deploy wordpress +juju deploy ntp-master --to 2 +``` + +**Code block length**: Limit code blocks to approximately 40 lines. Longer blocks are rarely read; consider breaking them up or offering as downloadable files. + +**Separate input and output**: Don't combine commands and their output in one block. Separate them with explanatory text: + +Avoid: + +``` +juju status +environment: gce3 +machines: +... +``` + +Preferred: + +``` +Check the current state: +``` + +```bash +juju status +``` + +``` +This returns the current state of each unit: +``` + +``` +environment: gce3 +machines: +... +``` + +**Placeholders** + +Use uppercase within angle brackets for placeholders: ``, `` + +For longer code blocks, consider defining placeholders as environment variables: + +```bash +CHANNEL=1.30/stable +``` + +Then use them in commands: + +```bash +juju download easyrsa --channel=$CHANNEL +juju download kubernetes-worker --channel=$CHANNEL +``` + +This approach: +- Separates user-supplied data from commands +- Enables blocks to be copied without modification +- Reduces the chance of user errors + +**UI interaction guidance** + +Don't use UI elements as verbs or nouns in prose. Link them to actions: + +- Good: "Click **Save** to save your settings" +- Avoid: "**Save** your settings" (using button text as verb) + +**Interaction verbs**: +- Use `Click` for buttons (or `Tap` for primarily mobile products) +- Use `Select` for dropdowns, multiple options, or menu navigation +- Use `Press` for keyboard shortcuts and keys (NOT `Click`) + +Examples: +- Click **Settings** to open user settings +- Select the machines you want to register, then click **Save** +- Press `Ctrl + C` to copy +- Press the `Enter` key to continue +- Select **Preferences > Languages > English** (using `>` for navigation) + +**Formatting**: +- Bold UI elements: **Save**, **File**, **Settings** +- Use `>` for menu navigation: **File > New > Document** +- Italics for quoted UI text: Click the link in _"You can register new computers..."_ + +**Checkboxes**: Use `Select`/`Clear` or `Check`/`Uncheck` (consistent pairs): +- Select the **Enable firewall** checkbox +- Clear the **Add bookmark** checkbox + +**Icons vs buttons**: Minimize use of "icon" and "button" terminology unless needed for clarity. When using images, provide alt text or write the name directly after. + +**Configuration examples** + +Always include caption when known. + +Indentation: Use commonly recognized formatting: +- YAML files: 2-space indentation +- JSON files: 4-space indentation + +**Multi-line shell commands** + +Use backslash continuation or explicit line breaks: + +--- + +## Cross-references and links + +**Internal cross-references** + +Prefer native internal cross-references (`:ref:`, `:doc:`, `{ref}`, `{doc}`) +with semantic anchor labels. +Prefer these roles over plain relative links so link integrity is validated during docs builds. + +**First mention pattern** + +Link important terms only at first mention on a page. Avoid excessive linking. + +**Reference label convention** + +Use section-prefixed labels consistently. +Examples include `tutorial-*`, `how-to-*`, `exp-*`, and `ref-*`. + +--- + +**Command names** + +In example blocks, use exact subcommand syntax: + +``` +project-tool launch +project-tool connect +build-tool build +``` + +When inline, shorter references are acceptable: the `launch` command. + +**Command line terminology** + +Convention: Use [POSIX utility conventions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html) when discussing command-line syntax, options, arguments, and other CLI elements. + +--- + +## Documentation quality principles + +Use the following in addition to general Diátaxis guidelines: + +**Clarity** + +- State assumptions explicitly +- Define prerequisites clearly +- Avoid jargon without explanation +- Use consistent terminology + +**Usability** + +- Focus on actionable information +- Use direct imperatives for instructions +- Break complex tasks into clear steps +- Provide working examples + +**Precision** + +- Avoid ambiguous language +- Use exact commands and syntax +- Specify versions when relevant +- Maintain consistent structure diff --git a/.github/skills/documentation-verify/SKILL.md b/.github/skills/documentation-verify/SKILL.md new file mode 100644 index 0000000..fc6dd7d --- /dev/null +++ b/.github/skills/documentation-verify/SKILL.md @@ -0,0 +1,93 @@ +--- +name: documentation-verify +description: "Verifies documentation accuracy by cross-referencing claims, CLI commands, API signatures, and configuration against source code. Use when validating documentation correctness or checking code-docs consistency. Flags unsupported or outdated claims." +--- + +# Documentation Accuracy Verification + +## Scope + +Accuracy verification only: cross-reference documentation claims, +commands, API names, and configuration keys against repository evidence +in the same repository. Flag anything that cannot be verified. + +In docs-only repositories, treat documentation tooling and artifacts +(for example, `conf.py`, `Makefile`, Sphinx configuration, redirects, +and examples) as the primary evidence source. + +## Inputs + +- Changed documentation files (from `git diff`). + If `git diff` is unavailable or empty, use files explicitly provided + for review; otherwise, treat all documentation files under the detected + docs root as changed. +- Full repository artifacts relevant to documentation behavior. +- Test files and configuration schemas (when applicable). +- Documentation structure. + +--- + +## Workflow + +Follow this three-stage process to verify documentation accuracy: + +### Stage 1: Discovery Scan + +**Objective**: Identify documentation claims and form initial hypotheses. + +1. Run `git diff` to list changed documentation files. +2. Categorize changes into claim types (behavior, CLI, API, config, examples, error messages, etc.). +3. Form initial hypotheses: Supported, Unsupported, Speculative, Ambiguous, or Outdated. + +**For detailed categorization and hypothesis formation procedures**, see `references/verification_procedures.md` → Discovery Scan. + +--- + +### Stage 2: Verification Pass + +**Objective**: Verify every hypothesis with repository evidence. +Repository artifacts are the source of truth. + +**CRITICAL**: Complete verification before reporting any claims. + +1. Use **at least two search strategies** per claim (direct search, entrypoint tracing, test evidence, schema/validation search). +2. Apply claim-type-specific verification checklists (behavior, CLI, API, config, examples, errors, terminology). +3. Document evidence for each finding (file paths, line numbers, search commands). +4. Reclassify hypotheses based on verification results. +5. Apply false-positive prevention rules. +6. Cross-check documentation coverage. + +**For comprehensive verification checklists and classification rules**, see `references/verification_procedures.md` → Verification Pass. + +--- + +### Stage 3: Report Generation + +**Objective**: Present verified findings with evidence and conservative recommendations. + +1. Group findings by final classification (unsupported, outdated, incorrect, imprecise, speculative, inconclusive, no issues). +2. Format each finding using the standard template (doc claim, verification checklist, code evidence, assessment, recommended action). +3. Provide conservative change suggestions aligned with code reality. +4. Link to specific code artifacts (files, functions, structs, line numbers). +5. Integrate with other analysis findings (e.g., Diataxis compliance). + +**For report formatting template and change suggestion guidelines**, see `references/report_format.md`. + +--- + +## Constraints + +- Complete the verification pass (Stage 2) before reporting any claims. +- Provide repository evidence for all documentation consistency claims. +- Repository artifacts are the source of truth: flag documentation that + contradicts repository behavior, not vice versa. +- Do not claim documentation is "unsupported" without verification evidence + (at least two search strategies with explicit search and no-match confirmation). +- Do not report false positives. +- Do not prefer "unsupported" when docs are vague or imprecise; use accurate classifications. +- Do not recommend changing implementation artifacts to match docs as the + primary action; documentation should be adjusted to match repository reality. + +## Output + +Only verified findings with evidence make it to the final report. Do not include intermediate hypotheses or reasoning. diff --git a/.github/skills/documentation-verify/references/report_format.md b/.github/skills/documentation-verify/references/report_format.md new file mode 100644 index 0000000..de6a96a --- /dev/null +++ b/.github/skills/documentation-verify/references/report_format.md @@ -0,0 +1,144 @@ +# Documentation Verification Report Format + +This reference defines how to structure and format the final verification report. + +--- + +## Report Structure + +### 1. Group Findings by Classification + +Organize findings into these categories: + +- **Confirmed unsupported**: Docs describe behaviour or options not present in code +- **Docs outdated**: Code exists but with different values or behaviour than documented +- **Docs incorrect**: Code contradicts doc claim +- **Docs imprecise**: Code behaviour more nuanced than docs suggest +- **Docs speculative**: Describes intended future behaviour (not yet implemented) +- **Inconclusive**: Cannot verify (requires human review) +- **No issues found**: All doc claims backed by code (state this explicitly) + +--- + +## Finding Format Template + +For each verified finding, use this structure: + +````markdown +**Doc Claim**: [File path:line] "[Quoted claim from docs]" + +**Verification Checklist**: +- [ ] Search strategies used: [list at least two strategies] +- [ ] Code location(s) checked: [file paths] +- [ ] Test evidence: [test file/function or "Not found"] +- [ ] Schema/validation: [struct/parser location or "Not found"] + +**Code Evidence**: +- **Expected**: [What docs claim should exist] +- **Found**: [What code actually shows, with file:line references] +- **Assessment**: [Supported | Unsupported | Outdated | Incorrect | Imprecise | Inconclusive] + +**Issue**: [Classification from list above] +- [Brief description of mismatch] + +**Recommended Action**: +- [File path]: [Specific minimal edit to restore correctness] +- Rationale: [Why this edit aligns docs with code] +- Alternative: [If docs are ahead of code, suggest opening an issue or reverting speculative claim] +```` + +--- + +## Conservative Change Suggestions + +When recommending actions, follow these guidelines: + +### For "Docs Outdated" +Update specific values or behaviour descriptions to match current code. + +**Example**: +``` +Recommended Action: +- docs/config.md:42: Change default value from `timeout: 30s` to `timeout: 60s` +- Rationale: Code shows default in config/defaults.go:15 is time.Duration(60 * time.Second) +``` + +### For "Docs Incorrect" +Correct the claim with precise wording from code. + +**Example**: +``` +Recommended Action: +- docs/api.md:78: Change "returns HTTP 200 on success" to "returns HTTP 201 on success" +- Rationale: Handler at handlers/create.go:45 returns http.StatusCreated (201) +``` + +### For "Docs Imprecise" +Add qualifiers, conditions, or edge-case notes. + +**Example**: +``` +Recommended Action: +- docs/cli.md:120: Add note "Only available when --experimental flag is enabled" +- Rationale: Feature gated behind ExperimentalMode check at cmd/feature.go:33 +``` + +### For "Confirmed Unsupported" +Revert or remove unsupported claim. If claim represents intended behaviour, change to future tense and add note. + +**Example**: +``` +Recommended Action: +- docs/features.md:89: Remove claim about auto-retry functionality +- Alternative: If feature is planned, change to "Auto-retry functionality is planned for future release" +``` + +### For "Docs Speculative" +Mark as future or intended, not current behaviour. + +**Example**: +``` +Recommended Action: +- docs/roadmap.md:15: Change "The system supports" to "The system will support (planned)" +- Rationale: No implementation found; appears to be planned feature +``` + +### For "Inconclusive" +Provide specific human review action. + +**Example**: +``` +Recommended Action: +- Request human review: Cannot locate implementation for documented retry logic +- Check: Is this implemented via external library? Search plugin system +``` + +--- + +## Linking to Code Artifacts + +Always reference: +- Specific files with line numbers (e.g., `auth/handler.go:145-167`) +- Function or struct names (e.g., `parseConfig()`, `ServerConfig struct`) +- Test files that exercise the behaviour (e.g., `auth_test.go:TestLoginSuccess`) +- Search commands used (e.g., `grep -r "timeout" config/`) + +--- + +## Report Integration + +- Prioritize code backing findings appropriately (blocking issues for incorrect or unsupported claims) +- Cross-reference with Diataxis compliance findings to identify if inaccuracies stem from category misalignment +- Prepare evidence-based recommendations with code references + +--- + +## Final Output Rule + +**Only verified findings with evidence make it to the final report.** + +Do NOT include: +- Intermediate hypotheses +- Reasoning process +- Unverified claims +- Speculation without code backing diff --git a/.github/skills/documentation-verify/references/verification_procedures.md b/.github/skills/documentation-verify/references/verification_procedures.md new file mode 100644 index 0000000..0ef779c --- /dev/null +++ b/.github/skills/documentation-verify/references/verification_procedures.md @@ -0,0 +1,180 @@ +# Documentation Verification Procedures + +This reference provides comprehensive procedures for verifying documentation accuracy against source code. + +--- + +## Table of Contents + +1. [Discovery Scan Procedures](#discovery-scan-procedures) +2. [Verification Pass Checklist](#verification-pass-checklist) +3. [Evidence Documentation](#evidence-documentation) +4. [Classification Rules](#classification-rules) +5. [False-Positive Prevention](#false-positive-prevention) + +--- + +## Discovery Scan Procedures + +### Step 1: Identify Changed Documentation Claims + +Run `git diff` to list changed documentation files. For each changed file, categorize changes into: + +**Claim Categories:** + +- **Behaviour claims**: Assertions about how the project, commands, or features behave. +- **Options/defaults/constraints**: Documented flags, configuration keys, default values, allowed values, validation rules. +- **Examples**: Code samples, command invocations, YAML/JSON configurations, expected outputs. +- **CLI surface**: Command names, subcommands, flags, help text, output formats. +- **API surface**: REST endpoints, request/response formats, client method signatures, schemas. +- **Error messages**: Documented error text, exit codes, diagnostic output. +- **Terminology/renames/deprecations**: Changed names, deprecated features, migration paths. +- **Interface/component behaviour**: Connection types, interaction mechanics, isolation rules. + +### Step 2: Form Initial Hypotheses + +For each claim, assign a preliminary classification: + +- **Supported**: Claim appears to match code structure (preliminary). +- **Unsupported**: Claim appears inconsistent with code (preliminary). +- **Speculative**: Claim describes future or intended behaviour without code backing. +- **Ambiguous**: Unclear whether claim matches code (needs deeper investigation). +- **Outdated**: Claim may describe previous code behaviour. + +--- + +## Verification Pass Checklist + +**CRITICAL**: Repository artifacts are the source of truth. +Complete verification before reporting any claims. + +### Search Strategies + +Use **at least two distinct search strategies** per claim: + +1. **Direct identifier search**: Search for exact names, keys, constants, struct fields using `grep -r`, `git grep`, ripgrep, or language-specific tools. +2. **Entrypoint tracing**: Follow from CLI, config, or API entrypoint to implementation. +3. **Test evidence search**: Locate tests that exercise the claimed behaviour in test files. +4. **Schema/validation search**: Find parsers, validators, schema generators, struct tags, validation functions. + +### Verification Checklist by Claim Type + +#### Behaviour Claims + +- [ ] Locate implementation code path +- [ ] Verify behaviour matches documented description +- [ ] Check for conditional behaviour (flags, modes, edge cases) +- [ ] Confirm error handling matches docs + +#### Options/Defaults/Constraints + +- [ ] Find struct field or config key definition +- [ ] Extract actual default value from code +- [ ] Find allowed values (enums, validation statements, regex patterns) +- [ ] Verify constraint enforcement + +#### Examples + +- [ ] Confirm example syntax matches actual parser expectations +- [ ] If example shows command output, verify against golden test files or actual execution +- [ ] Confirm field names, indentation, and structure match code expectations +- [ ] Check that referenced flags and options exist in code + +#### CLI Surface + +- [ ] Locate command definition in the CLI framework location +- [ ] Verify command name, aliases, subcommands match +- [ ] Check flag definitions (name, shorthand, type, default, help text) +- [ ] Confirm help text matches command definition +- [ ] Verify output formatting (column headers, sorting) + +#### API Surface + +- [ ] Find route definition +- [ ] Verify HTTP method, path, versioning +- [ ] Check request/response struct definitions +- [ ] Confirm client method signature +- [ ] Verify backward compatibility + +#### Error Messages + +- [ ] Search codebase for exact error text or pattern +- [ ] Verify error is returned in documented scenario +- [ ] Check error message format follows style guide + +#### Terminology/Renames/Deprecations + +- [ ] Search for old name to confirm it is truly deprecated or removed +- [ ] Find deprecation markers, aliases, or migration helpers +- [ ] Check changelog, release notes, or version gating logic +- [ ] Verify new name exists and is used consistently + +--- + +## Evidence Documentation + +### For Claims Supported by Code + +Document: +- File path, function or struct, and line range +- Assessment: `Supported (verified at [file:line])` + +### For Claims Not Supported by Code + +Document: +- Searches performed (at least two strategies with specific search terms) +- What was expected versus what was found +- Assessment: `Unsupported (expected [X], found [Y] at [file:line])` + +### For Inconclusive Claims + +Document: +- Search attempts performed +- What evidence is missing or ambiguous +- Assessment: `Inconclusive (needs human review: [specific check])` + +--- + +## Classification Rules + +Based on verification evidence, reclassify hypotheses using this decision matrix: + +| Original Hypothesis | Verification Outcome | Final Classification | +|---------------------|----------------------|----------------------| +| Unsupported | Found matching code | Retract claim (docs are correct) | +| Unsupported | Found code with different default | Docs outdated (needs value update) | +| Unsupported | No code evidence after thorough search | Confirmed unsupported (docs ahead of code) | +| Supported | Code contradicts doc claim | Docs incorrect (needs correction) | +| Ambiguous | Tests confirm behaviour | Supported (test-backed) | +| Ambiguous | Cannot locate relevant code | Inconclusive (flag for human review) | + +--- + +## False-Positive Prevention + +Apply these rules to avoid false positives: + +1. **Do not claim "unsupported" without documented code search evidence** + - Must have at least two strategies with explicit search terms + +2. **Prefer conservative classifications**: + - Prefer "inconclusive" over "unsupported" when code is complex or evidence is indirect + - Prefer "outdated" over "unsupported" when code exists but with different behaviour or values + - Prefer "imprecise" over "incorrect" when docs are vague but not technically wrong + - Retract claim entirely if verification confirms docs are accurate + +3. **Cross-check documentation coverage**: + - Before claiming "unsupported", verify the entity is not documented elsewhere + - Search the detected docs root for related terms, + alternative phrasings, and synonyms + - If claim is supported elsewhere, classify as "present but undiscoverable" instead + +--- + +## Content Completeness Check + +Before finalizing the report, check that all relevant topics are covered, especially for reference documentation: + +- **CLI**: Verify command-line interface changes are reflected in CLI reference documentation +- **Configuration**: Check that new configuration options are documented in the reference section +- **APIs and schemas**: Validate that API and schema modifications are properly documented diff --git a/docs/Makefile b/docs/Makefile index 43c2d34..4557124 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -110,7 +110,7 @@ pa11y: pa11y-install html find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) lint-md: pymarkdownlnt-install - @. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=$(SPHINXDIR) $(SOURCEDIR) + @. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=$(SPHINXDIR) --exclude=".github/" $(SOURCEDIR) vale-install: install @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py diff --git a/docs/conf.py b/docs/conf.py index 203692c..8136259 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -296,7 +296,9 @@ # Excludes files or directories from processing -#exclude_patterns = [""] +exclude_patterns = [ + ".github/**", +] # Adds custom CSS files, located under 'html_static_path'