From 5d6fd41da41c80a1a3342f4106f418520cebdf1e Mon Sep 17 00:00:00 2001 From: Patrick McFadin Date: Wed, 10 Jun 2026 18:24:40 -0700 Subject: [PATCH] Fix structural Antora errors in in-tree docs 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 --- .../cassandra/pages/developing/cql/cql_singlefile.adoc | 4 ++-- doc/modules/cassandra/pages/developing/cql/ddl.adoc | 2 +- .../developing/data-modeling/data-modeling_conceptual.adoc | 2 +- .../developing/data-modeling/data-modeling_logical.adoc | 6 +++--- .../developing/data-modeling/data-modeling_physical.adoc | 6 +++--- .../developing/data-modeling/data-modeling_queries.adoc | 2 +- .../pages/developing/data-modeling/data-modeling_rdbms.adoc | 2 +- .../developing/data-modeling/data-modeling_refining.adoc | 2 +- .../cassandra/pages/developing/data-modeling/intro.adoc | 4 ++-- .../pages/managing/tools/sstable/sstablemetadata.adoc | 2 +- 10 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc b/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc index 1d0bbbf257ef..f7d7416a3849 100644 --- a/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc +++ b/doc/modules/cassandra/pages/developing/cql/cql_singlefile.adoc @@ -1809,7 +1809,7 @@ doing'', you can force the execution of this query by using SELECT firstname, lastname FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING; -include::security.adoc[] +include::security.adoc[leveloffset=+1] [[types]] === Data Types @@ -2979,4 +2979,4 @@ names as their name. |`macaddr` |=== -include::changes.adoc[] +include::changes.adoc[leveloffset=+1] diff --git a/doc/modules/cassandra/pages/developing/cql/ddl.adoc b/doc/modules/cassandra/pages/developing/cql/ddl.adoc index 0f248282a062..34dfc5793548 100644 --- a/doc/modules/cassandra/pages/developing/cql/ddl.adoc +++ b/doc/modules/cassandra/pages/developing/cql/ddl.adoc @@ -112,7 +112,7 @@ replication factor independently for each data-center. The rest of the sub-options are key-value pairs, with a key set to a data-center name and its value set to the associated replication factor. Options: -[cols=",,,",options="header",] +[cols=",,",options="header",] |=== |sub-option |type |description |`''` | int | The number of replicas to store per range in the provided datacenter. diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_conceptual.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_conceptual.adoc index 47b6e8769b20..3e28c34b9819 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_conceptual.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_conceptual.adoc @@ -30,7 +30,7 @@ underlined. Relationships between entities are represented as diamonds, and the connectors between the relationship and each entity show the multiplicity of the connection. -image::images/data_modeling_hotel_erd.png[image] +image::data_modeling_hotel_erd.png[image] Obviously, in the real world, there would be many more considerations and much more complexity. For example, hotel rates are notoriously diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_logical.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_logical.adoc index bdb36ecfdaab..ba91fae929d7 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_logical.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_logical.adoc @@ -34,7 +34,7 @@ informative way to visualize the relationships between queries and tables in your designs. This figure shows the Chebotko notation for a logical data model. -image::images/data_modeling_chebotko_logical.png[image] +image::data_modeling_chebotko_logical.png[image] Each table is shown with its title and a list of columns. Primary key columns are identified via symbols such as *K* for partition key columns @@ -51,7 +51,7 @@ dedicated tables for rooms or amenities, as you had in the relational design. This is because the workflow didn't identify any queries requiring this direct access. -image::images/data_modeling_hotel_logical.png[image] +image::data_modeling_hotel_logical.png[image] Let's explore the details of each of these tables. @@ -127,7 +127,7 @@ shows a logical data model for reservations. You'll notice that these tables represent a denormalized design; the same data appears in multiple tables, with differing keys. -image::images/data_modeling_reservation_logical.png[image] +image::data_modeling_reservation_logical.png[image] In order to satisfy Q6, the `reservations_by_guest` table can be used to look up the reservation by guest name. You could envision query Q7 being diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_physical.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_physical.adoc index 7e610a266670..f8a7fb51826b 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_physical.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_physical.adoc @@ -19,7 +19,7 @@ notation for physical data models. To draw physical models, you need to be able to add the typing information for each column. This figure shows the addition of a type for each column in a sample table. -image::images/data_modeling_chebotko_physical.png[image] +image::data_modeling_chebotko_physical.png[image] The figure includes a designation of the keyspace containing each table and visual cues for columns represented using collections and @@ -61,7 +61,7 @@ As you work to create physical representations of various tables in the logical hotel data model, you use the same approach. The resulting design is shown in this figure: -image::images/data_modeling_hotel_physical.png[image] +image::data_modeling_hotel_physical.png[image] Note that the `address` type is also included in the design. It is designated with an asterisk to denote that it is a user-defined type, @@ -86,7 +86,7 @@ first iteration of your physical data model design, assume you're going to manage this denormalization manually. Note that this design could be revised to use Cassandra's (experimental) materialized view feature. -image::images/data_modeling_reservation_physical.png[image] +image::data_modeling_reservation_physical.png[image] Note that the `address` type is reproduced in this keyspace and `guest_id` is modeled as a `uuid` type in all of the tables. diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_queries.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_queries.adoc index a37494da83d6..cbcebb21c0c6 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_queries.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_queries.adoc @@ -53,7 +53,7 @@ to obtain detailed description of the hotel. The act of booking a room creates a reservation record that may be accessed by the guest and hotel staff at a later time through various additional queries. -image::images/data_modeling_hotel_queries.png[image] +image::data_modeling_hotel_queries.png[image] _Material adapted from Cassandra, The Definitive Guide. Published by O'Reilly Media, Inc. Copyright © 2020 Jeff Carpenter, Eben Hewitt. All diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_rdbms.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_rdbms.adoc index 2d4f1e3c6a4e..c045d7321463 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_rdbms.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_rdbms.adoc @@ -12,7 +12,7 @@ relationships from the conceptual model of hotels-to-points of interest, rooms-to-amenities, rooms-to-availability, and guests-to-rooms (via a reservation). -image::images/data_modeling_hotel_relational.png[image] +image::data_modeling_hotel_relational.png[image] == Design Differences Between RDBMS and Cassandra diff --git a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_refining.adoc b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_refining.adoc index 282c73cb60ed..e6231fcbd232 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_refining.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/data-modeling_refining.adoc @@ -188,7 +188,7 @@ the original design is shown in the figure below. While the `month` column is partially duplicative of the `date`, it provides a nice way of grouping related data in a partition that will not get too large. -image::images/data_modeling_hotel_bucketing.png[image] +image::data_modeling_hotel_bucketing.png[image] If you really felt strongly about preserving a wide partition design, you could instead add the `room_id` to the partition key, so that each diff --git a/doc/modules/cassandra/pages/developing/data-modeling/intro.adoc b/doc/modules/cassandra/pages/developing/data-modeling/intro.adoc index 2237b9e55916..02da507a3c5f 100644 --- a/doc/modules/cassandra/pages/developing/data-modeling/intro.adoc +++ b/doc/modules/cassandra/pages/developing/data-modeling/intro.adoc @@ -150,7 +150,7 @@ consist of `id` ( for partition key), magazine name and publication frequency as shown in Figure 1. .Data Model for Q1 -image::images/Figure_1_data_model.jpg[image] +image::Figure_1_data_model.jpg[image] Another query (Q2) is to list all the magazine names by publisher. For Q2 the data model would consist of an additional attribute `publisher` @@ -159,7 +159,7 @@ sorting within a partition. Data model for Q2 is illustrated in Figure 2. .Data Model for Q2 -image::images/Figure_2_data_model.jpg[image] +image::Figure_2_data_model.jpg[image] == Designing Schema diff --git a/doc/modules/cassandra/pages/managing/tools/sstable/sstablemetadata.adoc b/doc/modules/cassandra/pages/managing/tools/sstable/sstablemetadata.adoc index bb7262d9ffbe..ddd8605c82dd 100644 --- a/doc/modules/cassandra/pages/managing/tools/sstable/sstablemetadata.adoc +++ b/doc/modules/cassandra/pages/managing/tools/sstable/sstablemetadata.adoc @@ -337,7 +337,7 @@ seconds |Count Row Size Cell Count |two histograms in two columns; one represents distribution of Row Size and the other represents distribution of Cell Count -|Estimated cardinality an estimate of unique +|Estimated cardinality |an estimate of unique values, used for compaction |EncodingStats* minTTL |in epoch milliseconds |EncodingStats* minLocalDeletionTime |in epoch seconds