reStructuredText Writer Skill#

Purpose#

The restructuredtext-writer skill provides expert guidance for processing reStructuredText (RST) files, building Sphinx documentation, and ensuring high-quality content. It is specifically designed to help maintain documentation projects like ReadShade.

Core Capabilities#

  • Content Creation: Expert assistance in writing and updating documentation using plain English and an active voice.

  • Project Setup: Guidance on creating new Sphinx projects with sphinx-quickstart.

  • Formatting: Large-scale formatting and linting recommendations (e.g., using doc8 or restructuredtext-lint).

  • Advanced RST: Detailed explanations and examples for directives, roles, tables, and cross-referencing.

  • Build Management: Assistance with compiling HTML documentation and managing multiple builders (PDF, EPUB).

Usage#

This skill is intended to be used with an AI agent (such as Gemini CLI or Claude Code) when working within a Sphinx-based documentation project.

Compiling Documentation#

To build the HTML version of the documentation (like ReadShade):

On Linux/macOS#
make html
On Windows#
.\make.bat html

The output will typically be located in the build/html/ or _build/html/ directory.

Documentation Assistance#

You can ask the AI agent to:

  • “Add a new section about [topic] to the index page.”

  • “Format this table correctly in reStructuredText.”

  • “Check for broken links or linting errors in this file.”

  • “Explain how to use the ``toctree`` directive with the ``:glob:`` option.”