Split Generated Library Docs Into Draftable Structure and Owned Warranties

说明与用途

文档被拆分为机器生成的草稿部分和人工拥有的保修声明，受到CI验证并防止被覆盖。

问题

Generated docs often contain unverified warranty claims that can be copied into support issues, leading to misleading or legally risky statements.

结果

Documentation now clearly separates machine‑generated draftable content from human‑owned warranty claims, ensuring accurate, legally safe docs and CI enforcement.

工作流

• 1. Define a custody ledger (docs/custody.yaml) listing draftable surfaces, owned claim patterns, and owners.
• 2. Add HTML comments in Markdown to mark owned sentences (e.g., <!-- custody:owned owner=runtime claim=failure evidence=tests/test_retry.py -->).
• 3. Run a Python scanner that loads the ledger, walks docs/, and flags unowned warranty language or missing run stamps before fenced code blocks.
• 4. Configure CI to fail if the scanner reports any unowned warranties.
• 5. Regenerate documentation: draftable surfaces can be overwritten; owned sections remain untouched unless the named owner edits them.

证据

The scanner is a small Python program that maintainers can run locally and inside CI.

来源

Place owned claims in Markdown using an HTML comment that the renderer ignores and the scanner parses.

来源