Repository navigation
Conversation
The per-category graph tables share the shape
Graph | Num Nodes | Num Edges | <count col> | Size (MB) | Download, but the
count-column header was inconsistent across categories (c_alias, aa,
prov_derivation, vf, java_points_to, name_resolution, and the literal word
'grammar' on biological_uniprot). Per docs/graphs/index.rst ('Contents'),
that column is the number of vertex pairs reachable w.r.t. the canonical
grammar's language, not a grammar — so 'grammar' (issue #169) was simply
wrong, and the other names were arbitrary.
Unify the seven single-count-column categories on 'Reachable pairs', the
vocabulary the standalone docs/reachable_pairs.rst page already uses.
GRAMMAR_COLUMNS (the source of truth the table tools read to locate the
count cells) and the seven category pages are renamed in lockstep; cell
values are untouched. The rdf category (four per-grammar columns) is left
for the multi-row-header subtask.
Verified: utils/reachable_pairs_tables.py reports the tables in sync with
the CSV, and the module's tests + doctests pass.
…_columns The per-category graph tables were parsed with rows[0] assumed to be a flat single-row header, and both maintenance tools (archive_sizes and reachable_pairs_tables) looked up Download / Size (MB) / the count columns in rows[0] directly. That assumption breaks for any table whose header spans more than one row. Generalize the header handling in utils/archive_sizes.py: - GraphTable now carries a header_rows field (the :header-rows: count; 1 when the table declares none); _parse_table reads it and treats a bare '* -' line as a row start (the first cell of a row whose first entry is empty). - A new header_columns(table) helper returns the flat per-column header keys (the non-empty header cells of each column joined with ' / ' in row order), so callers locate columns by key rather than by a bare rows[0] cell. - update_table / main / _table_urls locate Download / Size (MB) via header_columns and iterate data rows from table.header_rows onward; the Size-column insertion now targets the last header row. reachable_pairs_tables.update_category_columns now locates each count column by its flat key (header_columns) and iterates data rows from header_rows. This is the substrate for issue #169's unified table design: the rdf count columns will carry flat keys like 'Reachable pairs / subClassOf' (S3), which the parser resolves the same way single-row tables do. Single-row tables (yet all the dataset tables) produce the same flat keys as before, so existing behavior is preserved. Covered by new multi-row tests plus the existing single-row suite (39 tests green, in-sync check passes).
…' prefix The rdf category table has four count columns (one per grammar language). They were headed by bare grammar names (subClassOf, subClassOf_type, type, broaderTransitive), inconsistent with the seven other categories that now use 'Reachable pairs' (S1). Unify them under a per-column prefix: each rdf count column is headed 'Reachable pairs / <grammar>' (e.g. 'Reachable pairs / subClassOf'), mirroring the flat-key form the table parser resolves (header_columns, S2). The rendered page keeps the 'Reachable pairs' / '<grammar>' split on two visual lines via the inline literal, keeping the narrow columns from the long bare names while staying a single-row list-table. GRAMMAR_COLUMNS (the source of truth for the table tools) and docs/graphs/ rdf.rst are updated in lockstep. Verified: the in-sync check passes, the module tests pass, and a Sphinx build renders the new headers with no list-table errors.
The user chose option 1: the rdf table stays a single-row list-table with a unified 'Reachable pairs / <grammar>' prefix per count column (rendered on two visual lines), rather than a merged multi-row header. Record the resolution and mark S2/S3 done.
Per user guidance, old_graphs is historical data and does not need to be maintained by the docs-table tools. Drop 'old_graphs/index.rst' from archive_sizes.GRAPH_TABLE_FILES so the size tool no longer HEADs (or can rewrite) the old-graphs table, and update the module docstring to describe only the per-category graph tables. The old_graphs page still renders unchanged; it is simply outside the tool's scope. No test references the file list, so the existing archive_sizes tests (all synthetic tables) are unaffected.
…talog
The 'Contents' section of the graph catalog described the count column
without naming its header. Update it to state that the count column is
titled 'Reachable pairs' across all categories, and that categories with
several grammar languages (e.g. RDF) prefix each column with the grammar
name ('Reachable pairs / <grammar>'). This is the last subtask of #169, so
this commit carries the closing keyword.
Closes #169
…s tests The new tests pass per-column (header, grammar) pairs to update_category_columns, whose parameter is list[tuple[str, Optional[str]]]. Annotate the literals so the type checkers (ty / pyright) accept them; the values are unchanged.
The field-sensitive-alias pages render the edge label f_r_i as a TeX double subscript, which MathJax rejects with "Double subscripts: use braces to clarify" (issue #173); seven grammar pages use & alignment tabs in plain display math, which MathJax rejects with "Misplaced &" (issue #174, discovered by validating every docs snippet with the MathJax 4.1.3 engine the site loads). - f_r_i -> f_{r\_i} in the 10 per-graph Edges Statistics tables and the FSA canonical-grammar block: braced subscript with escaped inner underscore, the same convention as \textit{store}_{r\_f} on the java_points_to pages, faithfully rendering the label string. - Wrap the seven &-aligned grammar blocks in \begin{aligned} ... \end{aligned}: alignment tabs are only legal inside an alignment environment; line content is unchanged. All 574 docs math snippets now compile cleanly in the MathJax 4.1.3 oracle (tex2mml, display mode per snippet kind). Closes #174
Hand-crafted TeX pattern checks can never cover every error the renderer rejects (issue #173 slipped past the #127-era underscore check). The systematic fix is to validate with the standard tooling: the MathJax engine itself, run on Node through the officially supported 'mathjax' npm package entry point (require('mathjax').init + tex2mml). A snippet the engine cannot parse yields <merror> nodes carrying the exact message shown on the deployed page, so checker and renderer cannot disagree. - package.json + package-lock.json at the repo root pin mathjax 4.1.3, the version the browser bundle serves (Sphinx 9's mathjax@4 default). - utils/check_math_snippets_node.cjs: pure stdin->stdout oracle (JSON array of {file, line, display, snippet}; one line per broken snippet; exit 0/1/2 for clean/broken/malfunction). - docs/conf.py: mathjax_js pinned to mathjax@4.1.3 so the browser loads exactly the version the guard validates with (no drift). - tests.yml + coverage.yml: npm ci step (Node is preinstalled on all runner OSes); developer.rst documents the Node >= 20 + npm ci prerequisite. - tests/utils/test_check_math_snippets_node.py pins the observable contract: broken snippets (double subscripts, text-mode underscore, unbalanced braces, dangling script, double exponent, misplaced &) are reported with the engine's messages; valid snippets (including f_{r\_i} and aligned blocks) pass; bad input exits 2.
…ocstrings The hand-crafted pattern checks of the #127-era guard can only reject the patterns someone thought to encode; issue #173 (double subscripts) proves the gap. Rewire the guard to the S2 oracle so the validator is the renderer: every snippet is compiled by the MathJax engine and reported with the engine's own error message. - utils/check_math_snippets.py: extract_math_snippets now returns (line, snippet, display) triples (display mode must match how the browser renders the snippet); the hand-crafted TeX pattern code (_TEXT_MODE_RE, _text_mode_groups, _has_unescaped_underscore, find_broken_snippets) is deleted; check_snippets batches all items through one oracle run; check_package scans every flpq_data docstring (rendered on the autodoc reference pages, same failure mode); main gains --package and runs both scans; missing node/node_modules fails loudly instead of skipping. - tests: extraction tests updated to the triple form; broken/valid cases now run through the real engine; docstring, missing-node, and real-tree/real-package tests added. - developer.rst: the Test pipeline section describes the engine-backed guard and its docstring coverage.
The guard now runs at commit time (local pre-commit hook, always_run — it is fast, ~2-3 s, and the failure it catches only surfaces otherwise on the deployed site), not just in the test suite. developer.rst lists the hook in the Quality checks enumeration (the config file stays the source of truth), and the changelog records the two fixes and the engine-backed guard. Fixes #173 Fixes #174
The plan file was maintained in the working tree and mirrored to the issue #173 comment after each subtask, but never committed; the code review caught the uncommitted state. Its content matches the mirrored comment (all four subtasks [done] with their commit hashes).
…ology The quality gate's link check (the CI "Check links" step, run locally per the no-push rule) reports http://www.ebusiness-unibw.org/ontologies/eclass/5.1.4 as broken: the university removed the /ontologies/ subtree from its site (its redirector mangles the path and the target 404s; verified directly, not a datacenter-IP block). The URL is the Source link of docs/graphs/data/eclass.rst and the Origin link of the historical docs/old_graphs/data/eclass.rst. Both now point to the Wayback Machine snapshot of the original artifact (eclass_514en.owl, archived 2016-03-09): the original landing page was a 303 redirect to exactly this file, so the links serve the same content as before. The snapshot is verified to be the eClassOWL 5.1.4 ontology (40 MB RDF/XML, "eClassOWL Version 5.1.4") and resolves with HTTP 200. No linkcheck_ignore entry: the ignore list is for rate-limited sites, not dead URLs; a dead link must not stay visible on the deployed page. Closes #173
S5 (the gate-discovered eclass link repair) is marked [done] with its commit hash, and its Tests line records the junit.org environmental ruling. Mirrored to the issue #173 plan comment.
The #169 fix (uniform `Reachable pairs` count-column names on the graph tables) is user-visible on the deployed site but was not recorded in CHANGELOG.md: the task's detailed plan carried no changelog subtask. Add the entry to the [Unreleased] Fixed section before the 6.1.2 release so the release notes reflect the change.
The tests workflow fails on windows-latest: MathJax's node entry
resolves components to plain absolute paths
(D:/.../node_modules/mathjax/input/tex.js) and loads them with
import(), but Node's ESM loader rejects absolute paths without a URL
scheme on Windows ("Only URLs with a scheme in: file, data, and node
are supported ... Received protocol 'd:'"). MathJax's own context.path
converter deliberately skips the file:// prefix in CJS contexts, so
the CJS entry (require('mathjax')) cannot produce import()-compatible
paths on Windows.
Override the loader's require function to convert absolute paths to
file:// URLs (pathToFileURL) before importing; relative paths and
node: specifiers pass through unchanged. Behavior on POSIX is
unchanged (file:// URLs are equally valid there).
The style job fails on every push: the check-math-snippets pre-commit hook (always_run, added for #173) requires node_modules/mathjax, but lint.yml never ran npm ci — only tests.yml did. Add the same "Install MathJax with npm" step before the pre-commit pass.
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
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.
Merge
devintomasterfor the 6.1.2 release (patch: documentation and dev-tooling only, no changes to the public API; dataset prefix stays at 6.0.0).What this carries:
Reachable pairsname (the rdf page's per-grammar columns prefixedReachable pairs / <grammar>, issue Incorrect column name #169).f_r_idouble subscripts on the field-sensitive-alias pages (issue [BUG] Double subscripts: use braces to clarify #173) and the&-aligned grammar blocks wrapped in\begin{aligned}(issue [BUG] Misplaced & in display math: grammar blocks not rendered #174).6.1.2inconfig.py/pyproject.toml, the changelog promoted from[Unreleased]to[6.1.2] - 2026-10-28.After this merges,
v6.1.2is tagged onmaster; the Publish workflow then builds the sdist/wheel, publishes them to PyPI (Trusted Publishing), and creates the GitHub Release with the[6.1.2]changelog section. The PR's Publish check pre-publishes to TestPyPI as a packaging validation for exactly this code.Task issues #169, #173, and #174 close via their
Closes #Ncommit references when this lands on master.