pmcfadin opened a new pull request, #4877: URL: https://github.com/apache/cassandra/pull/4877
Fixes the three structural (non-xref) error classes surfaced by the Antora 3 trial build of the in-tree docs. Child of epic CASSANDRA-21314; together with CASSANDRA-21449 this blocks the Antora 3 reland (CASSANDRA-21315), which is gated on a zero-error build. ### What changed **1. Missing data-modeling images (12 image macros, 7 pages)** All 12 referenced files (`data_modeling_*.png` ×10, `Figure_*_data_model.jpg` ×2) already exist in `doc/modules/cassandra/assets/images/` — nothing was ever lost, so nothing needed restoring from history. The page sources carry a stale `images/` path prefix from the original rST→AsciiDoc migration (`image::images/foo.png[]`), which Antora resolves against the module's image family as `assets/images/images/foo.png` and fails. The fix strips the prefix. Every image renders again; no figure was removed and no pedagogical content is affected. **2. Level-0 section errors (`security.adoc`, `changes.adoc`)** The standalone pages are fine — the errors come from `cql_singlefile.adoc`, which includes both pages whole, turning their `=` doctitles into illegal level-0 sections inside the including document. Fixed by adding `leveloffset=+1` to the two includes, so the included titles land as `==` sections — consistent siblings of the singlefile's existing `== CQL Syntax` / `== Terms` / `== Data Definition`. No prose changed; the rendered singlefile now nests "Database Roles" and "CQL Changes" as proper h2 sections. **3. Malformed tables (2 sites)** - `developing/cql/ddl.adoc` — the `NetworkTopologyStrategy` options table declared four columns (`cols=",,,"`) while every row has three cells. Corrected the spec to `cols=",,"`. - `managing/tools/sstable/sstablemetadata.adoc` — the value-explanation table row `|Estimated cardinality an estimate of unique values…` was missing its cell separator, leaving the 2-column table with an odd cell count. Restored the `|` between value and explanation. Table content is unchanged in both. ### Verification Antora 3 trial build (cassandra-website at the Antora 3.1.14 / Node 24 stack commit `897d1a67`, JSON logging, `./run.sh website build -e .xref-env -g -u cassandra:../cassandra -b cassandra:trunk`), measured with `xref-report.sh`: | | before (trunk `0d87b2d76a`) | after (this branch) | |---|---|---| | total error-level entries | **33** | **17** | | image | 12 | 0 | | section | 2 | 0 | | table | 2 | 0 | | xref | 17 | 17 | All 16 structural error entries are gone; the surviving 17 xref entries are byte-identical before and after (zero new errors). These 16 sites are the same population the trial-build log reported as 32 entries — that log carried each message twice. The remaining 17 xref errors are tracked separately (CASSANDRA-21449 and the Phase 4 long-tail under CASSANDRA-21342). ### AI-assistance disclosure This change was prepared with AI assistance (Claude). All edits were validated against a full Antora 3 site build as described above, and the before/after error inventories were diffed mechanically. Per project convention the AI attribution lives in this PR body rather than in commit trailers. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
