Refine Docs

Refine RLinf Docs

Bring a documentation page (or a whole section) up to the RLinf documentation style guide. Use this when writing a new page, rewriting an existing one, or doing a style/structure pass.

The single source of truth is docs/STYLE_GUIDE.md — read it first and apply it. This skill is the operating procedure; the style guide holds the exact rules. When the two disagree, the style guide wins.

When to use

• Editing/improving an existing page, or drafting a new one.
• A "make this page match our docs style" / "clean up these docs" request.
• Pair with the docs-check skill: refine-docs covers voice, structure, and style; docs-check covers facts, code references, and EN/ZH parity.

Workflow

1. Read docs/STYLE_GUIDE.md. It is authoritative.
2. Find both language files. Every page exists at docs/source-en/... and docs/source-zh/.... Refine both in the same pass and keep them in parity.
3. Classify the page, then apply the matching part of the guide:
   • Landing / section / sub-section index → cards or tables + a :hidden: toctree; one-line outcome; routed list. Never body bullet lists.
   • Recipe / example page (env, model, algorithm, SFT, robot) → the page anatomy: figure + intro → Overview (4 aligned cards) → Tasks + Observation and Action tables → Installation → Download the Model → Run It → Visualization and Results. Use the standard section names and the aligned card schema for that gallery subsection.
   • Concept / guide / reference / extending prose page → outcome-first intro, short sections, link out instead of inlining reference material.
4. Inspect the implementation behind the page. Verify public signatures, accepted input types, concrete return types, lifecycle behavior, config names, and representative call sites. When two related types are accepted by one API, explain what each represents and why both forms are valid. Pair this pass with docs-check for broader doc-to-code validation.
5. Plan the page as one continuous article. This is a basic requirement for every page type, not only Concepts, Guides, or code documentation. Write down the reader's starting state, the result promised by the page, and one sentence explaining why each section follows the previous one. Lead with the normal local workflow, then the common extension, composition with existing components, remote or distributed use, and finally ownership or scheduler internals. Use only the stages that fit the topic, but do not use the internal class hierarchy as the teaching outline.
   • Start the first prose sentence by stating directly what the page explains, enables, routes, or lets the reader look up. A leading figure may come first, but background prose may not postpone the page's purpose.
   • Give the rest of the page introduction a result, scope, and roadmap.
   • Give each section an opening paragraph that connects it to the established state and identifies the question it resolves; do not merely restate the heading.
   • Within a section, order paragraphs as distinction → API → example → interpretation → consequence or transition.
   • For an interface workflow, list every public call used by the primary example and explain it in caller order, including important inputs, return values, lifecycle effects, and how one result feeds the next call.
6. Apply the voice rules to every paragraph: second person, imperative, outcome first, no throat-clearing, short sentences, annotate non-trivial commands ("What this does: 1… 2…").
   • Explain before naming: concrete situation → ordinary-language distinction → exact API term → example → edge cases.
   • A heading must be understandable before its section is read. Do not put an unexplained implementation term in a heading and define it below.
7. Make examples demonstrate use, not only syntax. Introduce the outcome of each non-trivial code block before it and interpret the relevant result or lifecycle effect afterwards. For an extensible abstraction, show how the new component composes with an existing one, how a caller reads or controls it, and how it participates in the relevant task or environment.
8. Fix structure and labels: Title Case headings + standard names, one H1 per page, bare nav captions, cards/tables instead of bullet walls, footguns in a warning, correct axis ownership/placement.
9. De-duplicate: link to the canonical Reference / Evaluation page instead of re-explaining; if identical prose/commands repeat across 3+ pages, extract an underscore include partial (_name.rst).
10. Keep EN ↔ ZH parity: same structure and (translated) headings; identical, untranslated code identifiers (config keys, CLI flags, env/model names); stable :doc: / :ref: links (no hardcoded ReadTheDocs URLs); never glue **bold** directly between CJK characters. Write each language natively: preserve meaning and structure, not English clause order. Keep familiar developer terms in English when a Chinese translation would sound unusual or make the code harder to search. Keep each Chinese prose paragraph or prose list item on one source line. reStructuredText renders a hard wrap inside prose as a visible space, which leaves an unnatural gap between Chinese characters. Keep structural line breaks in headings, directives, tables, and code blocks.
11. Verify (the gate) — see below.