restructured-text
Guidelines for writing valid reStructuredText (.rst) in this repo (Sphinx).
When & Why to Use This Skill
This Claude skill provides comprehensive guidelines and best practices for writing valid reStructuredText (.rst) specifically for Sphinx documentation environments. It ensures structural consistency, correct heading hierarchies, proper list formatting, and the use of semantic inline markup to produce high-quality, error-free technical documentation that adheres to industry standards.
Use Cases
- Standardizing Technical Documentation: Ensure all .rst files follow consistent heading levels and indentation rules to maintain a professional and navigable Sphinx output.
- Semantic Markup Implementation: Correctly apply Sphinx roles such as :file:, :command:, and :envvar: to improve the clarity, formatting, and technical accuracy of software manuals.
- Documentation Error Prevention: Validate reStructuredText syntax during the writing process to avoid common pitfalls like broken cross-references, incorrect list nesting, or invalid character escaping.
- Automated Documentation Review: Assist developers and technical writers in reviewing pull requests to ensure that new documentation contributions comply with project-specific style guides and Sphinx requirements.
| name | restructured-text |
|---|---|
| version | 1 |
| description | "Guidelines for writing valid reStructuredText (.rst) in this repo (Sphinx)." |
| scope | "doc/**/*.rst" |
reStructuredText (Sphinx) guidelines
Core rules
- Treat
.rstas reStructuredText (not Markdown). Indentation and blank lines are semantic. - Prefer Sphinx structure over
.. include::for navigation: use.. toctree::so each page is a real document. - Avoid tabs; use spaces.
Headings
- Underlines must be at least as long as the title text.
- Keep heading levels consistent within a file.
Example::
Title
=====
Section
-------
Lists
- For enumerated/bulleted lists, indent continuation paragraphs under the list item and add a blank line between items when they contain multiple paragraphs.
Example::
1. Item title
Continuation paragraph (indented).
2. Next item
Inline markup
Escape characters that trigger markup when they are literal.
Prefer Sphinx roles for semantic markup:
- Filenames:
:file:(e.g. ``:file:`*.inp```). - Commands:
:command:. - Environment variables:
:envvar:(define them via.. envvar::somewhere in the docs).
- Filenames:
Common pitfall::
This breaks: CLEED *.res results file
Better::
Use :file:`*.res` results files
Links and references
Labels must use the underscore form:
.. _label_name:.Use ``:ref:`label_name``` for internal links.
Use explicit links for emails/URLs:
mailto:for email links.- Full URLs for external links.
Example::
See :ref:`file_formats` or email `support <mailto:someone@example.com>`_.