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.

Источник