Repository navigation
docs: align documentation with live sources and gate typography regressions - #222
Merged
Merged
Conversation
…rose Treats the source tree as the absolute authority for both pages. - progress output is now described in words instead of transcribing the U+2713 and U+00B7 glyphs that src/tablassert/progress.py emits, so the page stays accurate while carrying no non-ASCII characters. - docs/cli.md:263 used `snapshot\\|refresh\\|off`; the stray backslash escaped itself and the row split into extra cells. One backslash now renders the intended single cell (verified in the built site HTML). - sha256 verification is documented as best-effort, matching _fetch_prebuilt_sha256 returning None and warning instead of blocking. - quick-map prose fixed: unmatched terms print a `no matches` line and no table (cli.py:1252), and exit 2 covers bad flags plus a missing fullmap (cli.py:1216), not a fullmap that fails to open, which raises PyRuntimeError. - Stages are sequential (cli.py:317-466), so "six parallel stages" became six stages in sequence; the per-section phase list gains `cache` and `transform` (lib.py:1675-1677). - Worker caps now state the real formula min(CPUs, MemAvailable_GB / 2) with the 90 percent non-Linux fallback, and shard fan-out is bounded by 16 shards rather than "all available CPU threads". - Cache files are named by store suffix, not `.head.parquet`. - Removed the unsourced ~50% and ~Nx throughput claims, the stale external DuckDB shard aside, duplicated aria2 commentary, and the "ideal aria2 use case" and "rather than a million" marketing phrasings. - The 800085-of-2000085 figure is about 40 percent, so it no longer reads as "most of the edges", and its `--` separators are gone.
Every change here was verified against live code before it was written; three auditor claims were checked and rejected (the redb records table, the lookup_fullmap_terms entrypoint, and the producers clamp formula, which already matched fullmap.rs:2545). - utils.md named the SapBERT cache directory `.tablassert/sapbert/`; qc.py:27 sets MODEL = BASE / "sapbert-babel", and qc.md already said so. - namespace_uuid documented empty entries as dropped. They are not: rust/src/uuid.rs length-prefixes every part, so ["x","","y"], ["x","y"], and ["","x","y"] all hash differently (verified by running the extension). - merge_records keeps the lexicographically smallest conflicting scalar (ndjson.rs:302), not the first record's value. - The section store suffix list was missing `.linkouts` (cli.py:57,81). - qc.md claimed two fuzzy scorers; qc.py:233-236 runs three, and the token-set scorer shares fuzzy_partial_threshold (qc.py:243). Thresholds are named by the configurable parameters rather than hardcoded 70/80. - qc.md Stage 1 exact pass showed `original == preferred_name`; the code applies the alias map first (qc.py:207), so a configured alias can pass on exact match. - qc.md said the audit "does not run until the very end of the build". It runs as per-column ops inside resolution (lib.py:1436,1502). - Removed four unsourced Big-O "Performance:" lines and relabelled the invented "990 rows" cascade as unique pairs, which is what the cascade dedupes to. - lib.md's "after the SQL query" is gone: there is no SQL in the read path, the FREQUENCY column is computed in Polars over fetched rows (fullmap.py:116-117). - Taxon prose corrected in both api/lib.md and api/fullmap.md: the filter is category-blind and retains TAXON_ID 0 (fullmap.py:404-406), so it does not "return non-gene categories regardless of taxon". - Provenance prose no longer claims a "matched synonym" column; the schema has SOURCE_NAME, SOURCE_VERSION, and the normalized term (fullmap.py:104-113). - The resolve() example now applies level_one/level_two, because resolve_batch raises resolve-bad-specs when `<col>_two` is absent (fullmap.py:673-679). - Junk-term filter names the real dead-term set (fullmap.rs:360-378).
- The uuid_on_collision merge example listed `source_record_urls` and `upstream_resource_ids` as list fields, but biolink.py:451-453 deliberately keeps both inside `sources` entries and ALLOWED_EDGE_FIELDS (133 entries) excludes them. - Merge scalar arbitration is the lexicographic-minimum rule, not "first-wins"; the supporting_case_ids exemption sentence is reworded to match (the Rust fast path keeps the lexicographically smallest canonical value, ndjson.rs:302). - `rig.source_files` is written sorted and deduplicated (rig.py:670), not listed verbatim. - `rig.target_info` now names the ModelingCategories enum values a future_considerations category may take. - QC threshold rows state their live defaults (0.5 / 70 / 80 / empty) from models.py:1254-1257. - `data_access_locations` requires at least one entry (min_length=1, models.py:1027-1029). - The unsourced-percision framing "real 1.27M-edge graph" now names the dataset (MultiomicsKG 3.0.0), matching the CHANGELOG PR #122 measurements the numbers came from. - "maximally brittle" and "PR-worthy by construction" benefit phrasing replaced with mechanism statements. - The build-pipeline step list gains the seventh stage, Studying Graph, which runs under --qc (cli.py:466). - advanced-example.md renders the resolved statement in prose (subject Lactobacillus rhamnosus, predicate correlated_with, object 13C-tamoxifen) instead of the `--[predicate]-->` edge notation, removing the page's last prose arrow.
The changelog carried 217 em dashes, 51 rightwards arrows, 17 multiplication signs, 9 en dashes, 6 greater-than-or-equals, 5 minus signs, 5 ellipses, 3 left-right arrows, 2 almost-equals, 1 implies, and 1 superscript. All are now ASCII punctuation chosen by grammar: comma for appositives, semicolon for independent clauses, colon for definitions and lists, parentheses for parentheticals; rename and before/after arrows read "to", pipeline chains read "then"; math glyphs become >=, x, -, ~, ^2, ...; the one O(n^2) gains a caret. Verified mechanically before landing: 1035 lines in and out; all 76 release headings and their versions identical; all PR links, URLs, and digit sequences preserved in order (single documented insertion from the ^2 rewrite); zero characters above U+007F; zero prose arrows; zero space-flanked dash substitutes outside inline code and the release-heading separator. The docs guard suite (20 tests) and mkdocs --strict stay green. No release fact, version, count, or ordering was changed.
Sample output (README, tutorial): - Node records use `in_taxon` (a list) and always carry `provided_by`; the samples showed a nonexistent `taxon` scalar. Shapes confirmed by emitting real records through the build pipeline with the test-suite fake fullmap. - Edge id is a uuid3 (version nibble 3); one tutorial sample had a v4 nibble and README reused the tutorial's id for a different study, which the deterministic id scheme makes impossible. Samples now use distinct v3 ids. - p = 1e-3 maps to very_strongly_significant (coerce.py: band p <= 0.001); samples showed strongly_significant. - Inlined study name is "<table-config>.yaml SECTION <n>" (lib.py study_name), not the source CSV name. Both sample sets fixed, and prose now marks the edge records as abridged (real records also carry knowledge_level, agent_type, sources, original_subject/original_object). Installation: - `uv tool install` is an isolated console-script install and does not expose the Python API; both pages now direct API users to pip/uv add into their project environment. - Dropped the openpyxl fallback claim: no fallback engine exists, engine= calamine is the only path (openpyxl appears only in the test dependency group). - The missing-extra message example no longer misquotes errors.py:226 (the code emits an em dash separator); prose describes the first sentence and the text block quotes only the install command. Tutorial: `build-fullmap --output ./fullmap/data/fullmap.redb` simplified to `tablassert build-fullmap` (that path is the cli.py:1556 default); trimmed the lead paragraph's restating sentence. CONTRIBUTING: `## Daily edit -> check loop` renamed (prose arrow); dropped the machine-specific "20-30 seconds" pytest timing; added a docs-gate bullet (docs guard tests + mkdocs --strict) to the PR checklist. llms.txt: six -> five command implementations (cli.py registers five commands); `package -> extra` hyphenated. index.md: replaced the rhetorical bolded-question nav line with a plain pointer sentence.
tests/test_docs_style.py rejects regressions of the docs-overhaul fixes across README.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, llms.txt, and docs/**/*.md: characters above U+007F outside an explicit allowlist (currently only the e-circumflex in Gwênlyn Glusman, the author name in CITATION.cff), prose arrows (->, =>, <-, and unicode arrow variants) outside code spans and fences, space-flanked "--" em-dash substitutes in prose, and mid-prose double spaces. Inline code and fenced blocks are exempt because they carry real CLI flags, error text, and syntax. Landing the gate surfaced two leftovers the manual scan missed: CONTRIBUTING.md used " -- " as a sentence separator in the pre-commit prose, and table.md's category_override cell used "--" twice inside parentheticals. Both rewritten with commas/colons; the cell text is not pinned by any test (the "unsatisfiable --" hit in test_biolink.py is that file's own docstring). Ruff clean; the docs suites pass 217 tests; mkdocs --strict exits 0.
- rows/row_slice: NonNegativeInt in all three duplicated source tables (models.py:144-145); descriptions now say non-negative integer. - NodeEncoding.taxon: documents the live 9606 default and the null-disables escape (models.py:302). - category_override cell: population_context_qualifier is no longer a Tablassert grant; biolink-model 4.4.6 declared it natively and the tripwire removed the grant (biolink.py:595-602, CLASS_FIELD_OVERRIDES). The cell had contradicted the Annotations section, which already said this. - extracted_from_row_number: it is tracked internally and consumed into the row:<N> StudyResult ids, then dropped along with sheet_name; it is never emitted as an edge field, so "every edge automatically carries it" was wrong (lib.py:520-538). - rig section: artifact_base_url/artifact_base_path are Tablassert-only config keys, not RIG schema slots, and the "always schema-shaped" claim is replaced with the two real divergences (the artifact_* keys; requiredness differences where the upstream schema and template disagree, e.g. source_status, which Tablassert requires per the stricter template). - [aria2]: on macOS the sdist build hook fails, so do not install the extra there; build-fullmap uses the Python downloader. All claims verified against live models (uv run python model introspection) and the upstream RIG schema YAML. Docs guards 217 passed; mkdocs --strict 0.
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configuration
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
SkyeAv
changed the title
SkyeAv
added a commit
that referenced
this pull request
Oct 16, 2026
Cut 22.0.0 and bump the package version in pyproject.toml, CITATION.cff, and uv.lock. Major: the no_map node mode added in 21.0.0 is removed because verbatim nodes cannot derive a role and collapsed to biolink:NamedThing with flattened biolink:Association edges; configs setting the key are told why, then rejected (#221). The user-facing docs are corrected against the live sources, the changelog is normalized to plain ASCII, and tests/test_docs_style.py now gates typography regressions (#222). Changelog: - Versioned the 22.0.0 section from the two merged PRs (no Unreleased section existed), added PR links to both entries, and added the migration note for the no_map removal. Docs: none needed here; the docs pages themselves were aligned in #222 and the new style gate covers the CHANGELOG edit in the test suite. Testing: - make check -> exit 0: ruff check "All checks passed!", ruff format "71 files already formatted", pyright "0 errors, 0 warnings, 0 informations", pytest "1222 passed, 1 skipped in 23.81s", cargo test 127 + 11 (1 ignored) + 17 + 1 passed, clippy -D warnings clean - uv run mkdocs build --strict -> exit 0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Corrects the user-facing documentation against the Python/Rust sources, live CLI
behavior, and pipeline-emitted output; normalizes the remaining 323 non-ASCII
characters (317 in the changelog) to ASCII; and adds a test gate so the
typography and AI-tell fixes cannot regress. No source behavior changes; the
only test addition is the new gate.
Source-verified corrections
docs/cli.md,docs/fullmap.md): corrected auditor-flagged claims againstsrc/tablassert/cli.py,src/tablassert/fullmap.py, and live command output (progress-code glyph semantics, quick_map behavior, version/default facts).docs/api/qc.md,utils.md,lib.md,fullmap.md): QC thresholds confirmed live (SIMILARITY_THRESHOLD0.5, fuzz 70/80); log path~/.tablassert/log/tablassert.log; merge scalar-conflict rule (lexicographic minimum,rust/src/ndjson.rs:302);column_contextfixedFalsefor probe batches; taxon filter keepsTAXON_ID == 0rows alongside the requested taxon.docs/configuration/graph.md,table.md,advanced-example.md):source_record_urls/upstream_resource_idsare not edge columns (133-entryALLOWED_EDGE_FIELDSexcludes both); uuid_on_collision example fixed from "first-wins" to the lexicographic-minimum rule;rig.source_fileswritten sorted+deduplicated; QC default rows,data_access_locationsmin-length, and the category grant list corrected after biolink-model 4.4.6 absorbedpopulation_context_qualifier; rows/row_slice areNonNegativeInt;NodeEncoding.taxondocuments its live 9606 default;extracted_from_row_numberis consumed intorow:<N>StudyResult ids and dropped, never emitted. Therig:page now states thatartifact_base_url/artifact_base_pathare Tablassert-only config keys and where Tablassert requiredness deliberately diverges from the upstream RIG schema and template.README.md,docs/index.md,installation.md,tutorial.md,CONTRIBUTING.md,llms.txt,docs/examples.md): sample node/edge JSON regenerated from real pipeline output via the test suite's fake-fullmap harness (node records carryin_taxon+provided_by, notaxonscalar; edge ids are uuid3; p = 1e-3 maps tovery_strongly_significantper coerce.py banding; inlined study name is<config>.yaml SECTION <n>);uv tool installno longer presented as exposing the Python API; the openpyxl fallback claim removed (no fallback exists); missing-extra message example no longer misquoteserrors.py; five (not six) CLI commands;build-fullmapshown with its default output path.Style gate
tests/test_docs_style.py: rejects non-ASCII outside an explicit allowlist (currently only the e-circumflex in Gwênlyn Glusman, the author name in CITATION.cff), prose arrows, space-flanked--substitutes, and mid-prose double spaces across README, CHANGELOG, CONTRIBUTING, CODE_OF_CONDUCT,llms.txt, anddocs/**/*.md. Inline code and fences are exempt. Landing it caught two real leftovers, fixed in the same commit.Design
recordstable existence) to avoid churn.Testing
make check-> exit 0 (ruff clean, pyright 0 errors,1243 passed, 1 skipped, cargo test ok, clippy-D warningsclean) afteruv sync --group dev --extra cli --extra qc --extra log.uv run pytest tests/test_docs_style.py tests/test_docs_source_of_truth.py tests/test_docs_examples.py tests/test_docs_cli_coverage.py -q->217 passed.uv run mkdocs build --strict-> exit 0.Deferred: the stale redb version comment in
rust/Cargo.toml(code comment, not user-facing docs), and the "KGX-compliant" phrasing precision (the KGX spec validates against the Biolink Model; a mass rewording was left out of this PR).