You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pr@cassandra.apache.org by "pmcfadin (via GitHub)" <gi...@apache.org> on 2026/06/11 01:36:55 UTC
[PR] CASSANDRA-21448: Fix structural Antora errors in in-tree docs [cassandra]
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21448: Fix structural Antora errors in in-tree docs [cassandra]
Posted by "pmcfadin (via GitHub)" <gi...@apache.org>.
pmcfadin commented on PR #4877:
URL: https://github.com/apache/cassandra/pull/4877#issuecomment-5133815927
The testing was done with this command line:
./run.sh website build -e .xref-env -g -u cassandra:../cassandra -b cassandra:trunk
That was in the verification section
I'll note the formatting you mentioned. I was following how Stefan was doing it.
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21448: Fix structural Antora errors in in-tree docs [cassandra]
Posted by "michaelsembwever (via GitHub)" <gi...@apache.org>.
michaelsembwever commented on PR #4877:
URL: https://github.com/apache/cassandra/pull/4877#issuecomment-5128538800
the commit message is too long for my likes, it's wasting the reader's time (whom there are an infinite multiplying number of). bring it down to
```
Doc fixes for image paths, doctitle indents and tables
- Strip the stale images/ path prefix from 12 image macros on the data-modeling pages.
- Add leveloffset=+1 to the security.adoc and changes.adoc includes in cql_singlefile.adoc so the included doctitles
- Fix malformed tables in ddl.adoc and sstablemetadata.adoc
patch by Patrick McFadin; reviewed by Mick Semb Wever for CASSANDRA-21448
Assisted-By: <todo>
```
The exercise is rewriting the commit message, to what is concise and respectful of the reader's time, demonstrates you as the author have reviewed and understood what is being proposed in the patch.
and please add the `Assisted-By:` suffix line (according to the linux generative ai guidelines we're trying to build precedence on).
(also, tip, set your claude preferences to not hard wrap lines– makes draft editing a pita)
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21448: Fix structural Antora errors in in-tree docs [cassandra]
Posted by "michaelsembwever (via GitHub)" <gi...@apache.org>.
michaelsembwever commented on PR #4877:
URL: https://github.com/apache/cassandra/pull/4877#issuecomment-5128564707
How have we tested this ?
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org
Re: [PR] CASSANDRA-21448: Fix structural Antora errors in in-tree docs [cassandra]
Posted by "michaelsembwever (via GitHub)" <gi...@apache.org>.
michaelsembwever commented on PR #4877:
URL: https://github.com/apache/cassandra/pull/4877#issuecomment-5142421145
```
./run.sh website build -e .xref-env -g -u cassandra:../cassandra -b cassandra:trunk
```
thanks!
two things:
1. can you take a screenshot of how the fix looks
2. also test in-tree doc building with `ant gen-doc`
--
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: pr-unsubscribe@cassandra.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org