restructured-text

具有回归测试和 PR 创建的系统性错误修复工作流程。当用户要求"修复错误"、"调试问题"、"解决问题",或提供错误消息/失败测试来修复时使用。处理复现、根本原因分析、测试创建、修复实现和 PR 提交。

📖 中文导读:具有回归测试和 PR 创建的系统性错误修复工作流程。当用户要求"修复错误"、"调试问题"、"解决问题",或提供错误消息/失败测试来修复时使用。处理复现、根本原因分析、测试创建、修复实现和 PR 提交。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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 .rst as 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).

Common pitfall::

This breaks: CLEED *.res results file

Better::

Use :file:`*.res` results files
  • 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>`_.