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:
russell@unturf.com 2026-05-09 18:00:15 -04:00
parent 69e0a957ad
commit aad24d3cfe
No known key found for this signature in database
16 changed files with 111 additions and 105 deletions

View file

@ -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")

View file

@ -7,7 +7,7 @@ documents. This page is the orientation: what the system is, the
core abstractions you'll see in code and docs, and how they compose.
What arborist is
---------------
----------------
A reference implementation of two papers stacked:
@ -103,13 +103,13 @@ Every answer carries two stacked labels.
**Schema layer** — v9.8 trichotomy, persisted, drives cache lookups
and the audit chain:
============= =============================================================
============== =============================================================
``audit_mode`` meaning
============= =============================================================
STRICT every evidence unit verifies against context
HYBRID some claims source-grounded, some emerged from training
UNGROUNDED no evidence, or none verifies — purely emergent
============= =============================================================
============== =============================================================
STRICT every evidence unit verifies against context
HYBRID some claims source-grounded, some emerged from training
UNGROUNDED no evidence, or none verifies — purely emergent
============== =============================================================
**Display layer** — four-rung ladder for claim-lattice modes only;
renderer-only transformation, schema unchanged:

View file

@ -1,5 +1,5 @@
Arborist API Reference
=====================
======================
Generated from docstrings. Replaces the static modules.md.

View file

@ -167,7 +167,7 @@ Transform commitment shape (4×4 SE(3) homogeneous matrix,
rotational components quantized via SO(3) → axis-angle integer
encoding):
.. code-block:: json
.. code-block:: text
{
"kind": "frame_transform",

View file

@ -44,15 +44,15 @@ landed under the 2026-05-08 ``fbd99a8`` review:
Verdict thresholds
------------------
========================== ================== ============
Score / flags Verdict CLI exit
========================== ================== ============
``score >= SIGNAL_FLOOR`` **ACCEPT** ``0``
``[0, SIGNAL_FLOOR)`` **MARGINAL** ``0``
``score < 0`` **REJECT** ``1``
hard-regression flag **REJECT** ``1``
``NEG_INF_REGRESSION`` flag **REJECT** ``1``
========================== ================== ============
============================ ================== ============
Score / flags Verdict CLI exit
============================ ================== ============
``score >= SIGNAL_FLOOR`` **ACCEPT** ``0``
``[0, SIGNAL_FLOOR)`` **MARGINAL** ``0``
``score < 0`` **REJECT** ``1``
hard-regression flag **REJECT** ``1``
``NEG_INF_REGRESSION`` flag **REJECT** ``1``
============================ ================== ============
``SIGNAL_FLOOR`` defaults to ``0.05`` (5pp; matches
:file:`docs/bench-maxing.md`'s noise floor).