|
| 1 | +--- |
| 2 | +name: devguide-docs |
| 3 | +description: Help with edits, reviews, and validation for the CPython developer guide and its reStructuredText documentation. |
| 4 | +user-invocable: true |
| 5 | +allowed-tools: |
| 6 | + - read_file |
| 7 | + - grep_search |
| 8 | + - file_search |
| 9 | + - run_in_terminal |
| 10 | +--- |
| 11 | + |
| 12 | +# Devguide documentation helper |
| 13 | + |
| 14 | +Use this skill when working on the CPython Developer Guide repository, especially when editing or reviewing documentation files in `.rst` format. |
| 15 | + |
| 16 | +## Scope |
| 17 | + |
| 18 | +This repository documents contributor workflows, project policies, team processes, and technical guidance. The goal is to keep the documentation clear, correct, and easy to navigate for contributors. |
| 19 | + |
| 20 | +## Working approach |
| 21 | + |
| 22 | +1. Read the target page and any nearby pages needed for context, such as indexes, related sections, or neighboring docs. |
| 23 | +2. Keep the change focused on the user-visible issue or requested improvement. |
| 24 | +3. Preserve the repository's documentation voice: precise, technical, and contributor-focused. |
| 25 | +4. Follow the existing Sphinx reStructuredText conventions used in this repo, including heading hierarchy, lists, and directive syntax. |
| 26 | +5. Verify that any new page, section, or link is consistent with the surrounding navigation and index structure. |
| 27 | + |
| 28 | +## Repo conventions |
| 29 | + |
| 30 | +- Most source files use `.rst` and should follow the project's heading and indentation conventions. |
| 31 | +- Prefer clear prose that explains what contributors should do, why it matters, and any prerequisites. |
| 32 | +- Maintain consistency with existing terminology, especially for CPython-specific terminology and contributor workflow language. |
| 33 | +- Use relative links and references carefully so cross-references stay valid and readable. |
| 34 | +- Avoid unrelated cleanup or broad reformatting in the same change. |
| 35 | + |
| 36 | +## Validation |
| 37 | + |
| 38 | +When practical, run the smallest relevant documentation validation command, for example: |
| 39 | + |
| 40 | +- `make html` |
| 41 | +- `python -m sphinx -b html . _build/html` |
| 42 | + |
| 43 | +If a validation step is not available or is outside the scope of the request, clearly state that the content was not build-validated. |
| 44 | + |
| 45 | +## Avoid |
| 46 | + |
| 47 | +- Do not invent guidance or project claims that are not supported by the repo. |
| 48 | +- Do not break toctrees, section references, or generated docs. |
| 49 | +- Do not add unrelated formatting churn or autofixes. |
| 50 | +- Do not leave a change without checking the surrounding document structure. |
| 51 | + |
| 52 | +## Output expectations |
| 53 | + |
| 54 | +When editing documentation, summarize: |
| 55 | + |
| 56 | +- what changed, |
| 57 | +- where the change was made, |
| 58 | +- any validation or build checks that were run, |
| 59 | +- and any follow-up caveats if the docs were not fully rebuilt. |
0 commit comments