CASSANDRA-21448: Fix structural Antora errors in in-tree docs#4877
Open
pmcfadin wants to merge 1 commit into
Open
CASSANDRA-21448: Fix structural Antora errors in in-tree docs#4877pmcfadin wants to merge 1 commit into
pmcfadin wants to merge 1 commit into
Conversation
Fix the three structural error classes found by the Antora 3 trial build (child of CASSANDRA-21314, blocks the Antora 3 reland in CASSANDRA-21315): - Strip the stale images/ path prefix from 12 image macros on the data-modeling pages. The images all exist in the module's assets/images/ family; the rST-migration-era prefix made Antora resolve them to assets/images/images/* (24 build errors). - Add leveloffset=+1 to the security.adoc and changes.adoc includes in cql_singlefile.adoc so the included doctitles become level-1 sections in the include context instead of illegal level-0 sections (4 build errors). - Fix two malformed tables: a four-column cols spec on the three-column NetworkTopologyStrategy table in ddl.adoc, and a missing cell separator in the sstablemetadata.adoc value table (4 build errors). Full Antora 3 trial build before/after: 33 -> 17 error entries; all 12 image, 2 section, and 2 table errors at zero; the 17 surviving xref messages are byte-identical to the before build (tracked under CASSANDRA-21449). No visible prose is changed. patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21448
pmcfadin
force-pushed
the
CASSANDRA-21448-trunk
branch
from
1f93cee to
5d6fd41
Compare
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.
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 indoc/modules/cassandra/assets/images/— nothing was ever lost, so nothing needed restoring from history. The page sources carry a staleimages/path prefix from the original rST→AsciiDoc migration (image::images/foo.png[]), which Antora resolves against the module's image family asassets/images/images/foo.pngand 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 addingleveloffset=+1to 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— theNetworkTopologyStrategyoptions table declared four columns (cols=",,,") while every row has three cells. Corrected the spec tocols=",,".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 withxref-report.sh:0d87b2d76a)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.