docs: clear all 39 cold-build Sphinx warnings (truly green)
A `make docs-api-clean && make docs-api` cold rebuild now succeeds
with zero WARNING/ERROR lines (was 39).
Docstring fixes (RST hygiene — no semantic change):
- arborist/qa/{keys,runner,query,verify,quantifier,metacognition,dag,
evidence}.py — add blank lines around indented blocks, convert
ad-hoc indented sections to literal blocks (`::`), avoid line-broken
inline literals (e.g. UNKNOWN_EVIDENCE_ID), and replace nested
bracket/quote literals with cleaner wording.
- arborist/concepts/__init__.py — wrap function-signature listing in
a literal block so bare `*` (kwarg marker) doesn't trip docutils.
- arborist/store.py — blank line before bullet lists in module +
connect docstrings.
- arborist/evict.py — replace ad-hoc `{ ... }` enum block with prose.
Surface fixes:
- docs/_source/_ext/makefile_targets.py — escape `*` in auto-
generated Makefile target descriptions (covers `*-parallel`,
`*.dot`, `*.db`, `π*`, etc.) so the generator emits clean RST.
- docs/_source/index.rst, concepts.rst — extend title underlines
to match title length.
- docs/_source/concepts.rst, v8-fork-score.rst — widen first column
of grid tables so cells no longer overflow into the column margin.
- docs/_source/merkle-agi-v7w-spatial-temporal.rst — switch
pseudocode JSON block from `code-block:: json` to `text` (the
`<int32 x 3>` placeholders aren't valid JSON tokens).
Verification:
- make docs-api-clean && make docs-api → build succeeded, 0 warnings
- make test → 1588 passed, 28 skipped
- make chain-check-shards → 0 breaks across all 7 shards
- import-time SyntaxWarning escalation on edited modules → clean
This commit is contained in:
parent
69e0a957ad
commit
aad24d3cfe
16 changed files with 111 additions and 105 deletions
|
|
@ -133,6 +133,13 @@ def parse_makefile(makefile_path: Path) -> dict[str, str]:
|
|||
return targets
|
||||
|
||||
|
||||
def _escape_rst(text: str) -> str:
|
||||
# Bare `*` in description text (e.g. ``*-parallel``, ``*.db``,
|
||||
# ``π*``) trips the docutils inline-emphasis scanner. Escape every
|
||||
# asterisk so it renders literally.
|
||||
return text.replace("*", r"\*")
|
||||
|
||||
|
||||
def generate_rst(all_targets: dict[str, str], output_path: Path) -> None:
|
||||
"""Write a single RST page grouping every target by workflow phase."""
|
||||
lines = [
|
||||
|
|
@ -174,7 +181,7 @@ def generate_rst(all_targets: dict[str, str], output_path: Path) -> None:
|
|||
lines.append(" - Description")
|
||||
for name, desc in present:
|
||||
lines.append(f" * - ``make {name}``")
|
||||
lines.append(f" - {desc}")
|
||||
lines.append(f" - {_escape_rst(desc)}")
|
||||
lines.append("")
|
||||
|
||||
# Surface anything we forgot to categorize so it shows up in review.
|
||||
|
|
@ -196,7 +203,7 @@ def generate_rst(all_targets: dict[str, str], output_path: Path) -> None:
|
|||
lines.append(" - Description")
|
||||
for name, desc in sorted(leftover):
|
||||
lines.append(f" * - ``make {name}``")
|
||||
lines.append(f" - {desc}")
|
||||
lines.append(f" - {_escape_rst(desc)}")
|
||||
lines.append("")
|
||||
|
||||
output_path.write_text("\n".join(lines), encoding="utf-8")
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue