Docs Check

Docs Check

Quick Start

Use this skill when documentation changes may introduce mismatches with:

• Code and config source of truth
• Other existing docs in the same section
• English and corresponding Chinese docs

Always read reference.md first, then run the workflow below.

Two harnesses in this folder do the mechanical part; run them before reasoning about content:

# Does the page still build? Both Read the Docs projects use fail_on_warning.
python3 .agents/skills/docs-check/build_docs.py            # en + zh

# Does CJK punctuation break inline markup, loudly or silently?
python3 .agents/skills/docs-check/check_rst_markup.py      # needs docutils

# Does the page still name things the code has?
python3 .agents/skills/docs-check/check_doc_symbols.py

Inputs

Collect these inputs before reviewing:

• Changed doc files (or target docs to validate)
• Corresponding EN and ZH files for the same topic
• Related code/config files referenced by the docs

If scope is unclear, default to checking:

• docs/source-en/ and docs/source-zh/ counterparts
• rlinf/config.py (SupportedModel)
• rlinf/envs/__init__.py (SupportedEnvType)
• Referenced scripts under examples/, toolkits/, ray_utils/, and requirements/

Workflow

1. Read reference.md and extract the relevant checklist items.
2. Run the build harness for both languages and fix every warning:
   • python3 .agents/skills/docs-check/build_docs.py (add --lang zh to iterate faster on a Chinese-only failure).
   • The two Read the Docs projects build independently with fail_on_warning: true, so an English-clean page can still turn docs/readthedocs.org:rlinf-cn red. Never conclude "docs are fine" from one language.
   • Then python3 .agents/skills/docs-check/check_rst_markup.py for the inline-markup defects that render wrong without warning.
3. Verify doc-to-code correctness:
   • Commands exist and are runnable in principle.
   • Script/module paths in docs exist.
   • Config keys and values match real code/config names.
   • Model/env names match SupportedModel and SupportedEnvType string values.
4. Verify doc-to-doc consistency within one language:
   • Terminology is consistent across start/tutorials/examples/API pages.
   • New page is linked in the correct index/toctree.
   • No conflicting instructions between related pages.
   • Internal doc links use stable :doc:/relative links, not hardcoded ReadTheDocs URLs.
5. Verify EN-ZH parity:
   • Same topic coverage and section structure.
   • Same commands, config keys, and model/env identifiers.
   • Translations preserve technical meaning (do not rename code symbols).
   • Corresponding EN/ZH pages use equivalent stable internal links.
6. Verify natural-language flow:
   • Treat continuity as a requirement for every article, including landing, recipe, reference, and non-code prose pages. Adapt the depth of the lead to the page type, but do not exempt a page from establishing its purpose and order.
   • The first prose sentence after the title, or after a leading figure, states directly what the page explains, enables, routes, or lets the reader look up. Background must not delay the page's purpose until a later paragraph.
   • The page introduction establishes the reader's starting situation, the promised result, the topic boundary, and the order of the explanation.
   • Read the introduction followed only by each section's opening paragraph. They must form a coherent outline in which every section follows from the state established before it.
   • Each section opens by stating the question it resolves and its connection to the surrounding workflow; it does not begin abruptly with code, a table, an API identifier, or a fact unrelated to the previous section.
   • Paragraphs develop one argument in dependency order rather than forming a reorderable list of correct facts.
   • Every public operation in the primary example is explained in caller order, including the relevant input or return value and lifecycle effect. Each non-trivial code block has a stated purpose and an interpretation.
   • Start from a concrete reader question, explain the idea in ordinary language, then introduce the exact API term and example.
   • Headings, cards, and opening sentences do not introduce unexplained implementation terms. An identifier heading is appropriate only on a lookup-oriented API or reference page, or after the term is established.
   • English reads as direct colleague-to-colleague prose, without canned transitions, uniform paragraph rhythms, or promotional summaries.
   • Chinese follows natural Chinese logic rather than English clause order. Familiar developer terms stay in English when translating them would sound unusual or make the code harder to search.
   • Chinese uses restrained written technical language: neither casual chat nor bureaucratic prose.
   • Chinese prose paragraphs and prose list items stay on one source line. A hard wrap inside prose renders as a visible space between Chinese characters even when the source contains no typed space.
7. Report findings with severity and concrete fixes.