docs: add a documentation style guide and apply it to the remaining pages

AGENTS.md

@@ -30,6 +30,9 @@ Relevant entry points:
 - [Adding a New Expression](docs/source/contributor-guide/adding_a_new_expression.md) /
   [Adding a New Operator](docs/source/contributor-guide/adding_a_new_operator.md).
 - [Debugging Guide](docs/source/contributor-guide/debugging.md).
+- [Documentation Style Guide](docs/source/contributor-guide/style_guide.md): the terms to use for
+  how Comet runs a query, and the conventions for docs pages. Read it before editing `docs/source`,
+  `README.md`, or the `.doc(...)` strings in config classes.
 - [Backporting to Release Branches](docs/source/contributor-guide/backporting.md): a fix that
   goes to one release branch also goes to every newer one. Cherry-pick with `-x`, and never add
   an unrelated change to a backport pull request.

docs/source/about/gluten_comparison.md

@@ -27,7 +27,7 @@ We recommend trying out both Comet and Gluten to see which is the best fit for y
 ## Architecture
 
 Comet and Gluten have very similar architectures. Both are Spark plugins that translate Spark physical plans to
-a serialized representation and pass the serialized plan to native code for execution.
+a serialized representation and pass the serialized plan to an engine written in Rust or C++ for execution.
 
 Gluten serializes the plans using the Substrait format and has an extensible architecture that supports execution
 against multiple engines. Gluten 1.7.0 supports Velox and ClickHouse. A third backend, Bolt, a C++ engine from
@@ -39,11 +39,11 @@ does not plan to support multiple engines, but rather focus on a tight integrati
 
 ## Underlying Execution Engine: DataFusion vs Velox
 
-One of the main differences between Comet and Gluten is the choice of native execution engine.
+One of the main differences between Comet and Gluten is the choice of execution engine.
 
-Gluten uses Velox, which is an open-source C++ vectorized query engine created by Meta.
+Gluten uses Velox, which is an open-source C++ columnar query engine created by Meta.
 
-Comet uses Apache DataFusion, which is an open-source vectorized query engine implemented in Rust and is governed by the
+Comet uses Apache DataFusion, which is an open-source columnar query engine implemented in Rust and is governed by the
 Apache Software Foundation.
 
 Velox and DataFusion are both mature query engines that are growing in popularity.
@@ -59,13 +59,13 @@ must guard against manually at runtime. For a component that runs inside every S
 untrusted data, this reduces the risk of memory-corruption crashes and security vulnerabilities. DataFusion achieves
 this safety without a garbage collector, so there is no additional runtime overhead compared to C++.
 
-If users are just interested in speeding up their existing Spark jobs and do not need to implement UDFs in native
-code, then we suggest benchmarking with both solutions and choosing the fastest one for your use case.
+If you want to speed up your existing Spark jobs and do not need to implement UDFs in Rust or C++,
+benchmark both and choose the faster one for your workload.
 
 ## Community and Governance
 
-Comet is developed within the Apache DataFusion project, and its native execution is built directly on the
-DataFusion query engine. DataFusion is a broad, vendor-neutral community governed by the Apache Software Foundation
+Comet is developed within the Apache DataFusion project, and its Rust-implemented operators are built directly on
+the DataFusion query engine. DataFusion is a broad, vendor-neutral community governed by the Apache Software Foundation
 and used by many downstream projects beyond Comet. This means that engine-level improvements such as new operators,
 optimizer rules, and performance work are shared across the whole DataFusion ecosystem: work done for other
 DataFusion users benefits Comet, and work done for Comet benefits them in turn.
@@ -96,19 +96,19 @@ Gluten 1.7.0 supports Spark 3.3, 3.4, 3.5, 4.0, and 4.1.
 Spark 4.0 enables ANSI SQL semantics by default, which changes how arithmetic overflow, invalid casts, division by
 zero, and similar error conditions are handled. This is one area where the two projects currently differ.
 
-Comet implements ANSI semantics for the expressions it supports natively, including arithmetic overflow checks,
+Comet implements ANSI semantics for the expressions it supports, including arithmetic overflow checks,
 ANSI cast behavior, and `try_*` variants. Queries running with `spark.sql.ansi.enabled=true` continue to be accelerated.
 See the [Comet Compatibility Guide] for details on which expressions have full ANSI coverage.
 
 The Gluten Velox backend documents that ANSI mode is not supported: by default, any query executed with ANSI enabled
 falls back to vanilla Spark. Setting `spark.gluten.sql.ansiFallback.enabled=false` makes Gluten attempt to run such
-queries natively, but Gluten's developer documentation notes that the results do not yet match Spark. See the
+queries in Velox, but Gluten's developer documentation notes that the results do not yet match Spark. See the
 [Gluten Velox limitations] page for the current status.
 
-[Gluten Velox limitations]: https://apache.github.io/gluten/velox-backend-limitations.html
+[Gluten Velox limitations]: https://github.com/apache/gluten/blob/v1.7.0/docs/velox-backend-limitations.md
 
 For users adopting Spark 4.0 without disabling ANSI mode, this difference can have a significant impact on the
-fraction of a workload that runs natively.
+fraction of a workload that each project accelerates.
 
 ## Table Format Support
 
@@ -118,18 +118,20 @@ covers a broader set of table formats overall.
 Comet provides a native Iceberg scan built on iceberg-rust. It has been tested with Iceberg 1.5 and 1.8 through 1.11
 and supports Iceberg spec v1, v2, and v3, schema evolution, time travel and branch reads, positional and equality
 deletes and deletion vectors, encrypted v3 tables, REST catalogs, and S3-compatible object storage. For Iceberg
-writes, Comet can write the data files of eligible writes natively through iceberg-rust, an opt-in feature, and
-iceberg-java writes the rest and commits every write (see [Comet Iceberg writes]). Comet does not currently provide
-native integrations for Delta Lake, Hudi, or Paimon. See the [Comet Iceberg guide] for the full list of supported
-features and known limitations.
+writes, Comet can write the data files of eligible writes in Rust through iceberg-rust, an opt-in feature, and
+iceberg-java writes the rest and commits every write (see [Comet Iceberg writes]). For Delta Lake, Comet has an
+experimental, opt-in scan in a separate contrib module that no release publishes yet and that is off by default (see
+[Comet Delta Lake guide]). Comet does not currently provide integrations for Hudi or Paimon. See the
+[Comet Iceberg guide] for the full list of supported features and known limitations.
 
 [Comet Iceberg guide]: /user-guide/latest/iceberg.md
 [Comet Iceberg writes]: /user-guide/latest/iceberg.md#writes
+[Comet Delta Lake guide]: /user-guide/latest/delta.md
 
 Gluten ships dedicated modules for Iceberg, Delta Lake (2.3 through 4.1, depending on the Spark version), Hudi, and
 Paimon. Its [Iceberg documentation] says that reads of unpartitioned tables are offloaded, including tables with
 position deletes, while reads of partitioned tables mostly fall back to Spark, as do equality deletes and all writes.
-Users who need native acceleration for Delta, Hudi, or Paimon will find broader coverage in Gluten today.
+If you need acceleration for Delta, Hudi, or Paimon, Gluten covers more today.
 
 [Iceberg documentation]: https://github.com/apache/gluten/blob/v1.7.0/docs/get-started/VeloxIceberg.md
 
@@ -139,33 +141,33 @@ Comet relies on the full Spark SQL test suite (consisting of more than 24,000 te
 integration tests to ensure compatibility with Spark. Features that are known to have compatibility differences with
 Spark are disabled by default, but users can opt in. See the [Comet Compatibility Guide] for more information.
 
-[Comet Compatibility Guide]: https://datafusion.apache.org/comet/user-guide/latest/compatibility/index.html
+[Comet Compatibility Guide]: /user-guide/latest/compatibility/index.md
 
 Gluten also aims to provide compatibility with Spark, and includes a subset of the Spark SQL tests in its own test
 suite. See the Gluten [Velox backend limitations] page for known gaps, such as differences in the regular expression
 dialect (RE2 vs `java.util.regex`).
 
-[Velox backend limitations]: https://apache.github.io/gluten/velox-backend-limitations.html
+[Velox backend limitations]: https://github.com/apache/gluten/blob/v1.7.0/docs/velox-backend-limitations.md
 
 ## Codegen Dispatch
 
-When an expression has a native implementation with known semantic differences from Spark, or has no native
-implementation at all, Comet can run Spark's own generated code for that expression inside the native pipeline. Data
-is passed to the JVM in Arrow format, evaluated using Spark's byte-exact logic, and returned to the native pipeline for
+When an expression has a Rust implementation with known semantic differences from Spark, or has no Rust
+implementation at all, Comet can run Spark's own generated code for that expression inside the Comet pipeline. Data
+is passed to the JVM in Arrow format, evaluated using Spark's byte-exact logic, and returned to Rust for
 the rest of the query. Comet calls this the codegen dispatcher.
 
 This matters for two reasons:
 
 - **Correctness by default.** Expressions that are only partially compatible with Spark (for example, regular
   expressions, JSON functions, and some datetime and array functions) route through the codegen dispatcher by
-  default, so they produce results that match Spark exactly. The faster native path is opt-in per expression for
+  default, so they produce results that match Spark exactly. The faster Rust path is opt-in per expression for
   users who accept its differences.
-- **Fewer fallbacks.** Because the dispatcher keeps evaluation inside the native pipeline, a single unsupported or
+- **Fewer fallbacks.** Because the dispatcher keeps evaluation inside the Comet pipeline, a single unsupported or
   incompatible scalar expression does not force its operator back onto vanilla Spark.
 
 Gluten's closest equivalent is partial projection, which has been enabled by default since Gluten 1.3.0. When a
 projection contains expressions that the backend cannot run, including Scala and Hive UDFs, Gluten splits the
-projection so that vanilla Spark evaluates only those expressions and the rest of the projection runs natively.
+projection so that vanilla Spark evaluates only those expressions and the rest of the projection runs in Velox.
 Partial projection applies only to projections, so, for example, a filter that contains an unsupported expression
 still falls back to Spark. See the [Comet Compatibility Guide] for more detail on how the codegen dispatcher works and
 which expressions use it.
@@ -182,24 +184,24 @@ faster native Rust regex engine as an opt-in per expression for users who can ac
 Gluten's Velox backend evaluates regular expressions using the C++ RE2 engine, which uses a different dialect from
 `java.util.regex` and deliberately omits features such as backreferences and lookaround. Gluten falls back to Spark
 for patterns that RE2 cannot compile, so those return correct results without acceleration. Patterns that RE2 accepts
-run natively and can differ from Spark in edge cases: for example, `\s` does not match the vertical tab character.
+run in Velox and can differ from Spark in edge cases: for example, `\s` does not match the vertical tab character.
 Setting `spark.gluten.sql.fallbackRegexpExpressions=true` sends every regular expression function to Spark. See the
 [Gluten Velox limitations] page for details. Comet's codegen dispatcher avoids this trade-off by running Spark's own
-regex engine inside the native pipeline.
+regex engine inside the Comet pipeline.
 
 ## Scala and Java UDF Support
 
-The same codegen dispatcher lets Comet run Spark's existing Scala and Java scalar UDFs inside the native pipeline
-without any rewrite. A UDF's compiled code executes on Arrow data passed from the native pipeline, and, crucially,
-the presence of a UDF does not force the enclosing operator back to vanilla Spark: the surrounding native operators
-keep running natively while only the UDF itself is evaluated on the JVM. This covers functions registered via
+The same codegen dispatcher lets Comet run Spark's existing Scala and Java scalar UDFs inside the Comet pipeline
+without any rewrite. A UDF's compiled code executes on Arrow data passed from Rust, and, crucially,
+the presence of a UDF does not force the enclosing operator back to vanilla Spark: the surrounding operators
+stay in the Comet pipeline while only the UDF itself is evaluated on the JVM. This covers functions registered via
 `udf(...)`, `spark.udf.register(...)`, and SQL `CREATE FUNCTION ... AS 'com.example.MyUDF'`, including UDFs over
 complex nested types and UDFs composed with other Catalyst expressions and higher-order functions.
 
 This means users can adopt Comet without giving up their existing Scala and Java UDFs, and without rewriting them in
-the engine's native language. Hive UDFs are not covered and still fall back to Spark. Gluten's Velox backend supports
-native C++ UDFs, and its partial projection (see [Codegen Dispatch](#codegen-dispatch)) evaluates Scala and Hive UDFs
-in a projection with vanilla Spark while the rest of the projection runs natively. A UDF in a filter makes the filter
+Rust. Hive UDFs are not covered and still fall back to Spark. Gluten's Velox backend supports
+C++ UDFs, and its partial projection (see [Codegen Dispatch](#codegen-dispatch)) evaluates Scala and Hive UDFs
+in a projection with vanilla Spark while the rest of the projection runs in Velox. A UDF in a filter makes the filter
 fall back to Spark. See the [Comet Scala and Java UDF guide] for the full list of supported and unsupported cases.
 
 [Comet Scala and Java UDF guide]: /user-guide/latest/scala_java_udfs.md
@@ -239,6 +241,6 @@ management capabilities vs the complexities around installing C++ dependencies.
 Comet and Gluten are both good solutions for accelerating Spark jobs, and independent benchmarking shows they
 deliver similar overall performance. Comet currently has an edge for users on Spark 4.0 with ANSI mode enabled, for
 Iceberg workloads, and through its codegen dispatcher, which runs partially compatible or unsupported expressions with
-Spark's exact semantics inside the native pipeline. Gluten holds a small performance lead in the AWS Labs TPC-DS
-benchmarks and offers broader native integration with Delta Lake, Hudi, and Paimon, plus a second backend in
+Spark's exact semantics inside the Comet pipeline. Gluten holds a small performance lead in the AWS Labs TPC-DS
+benchmarks and offers broader integration with Delta Lake, Hudi, and Paimon, plus a second backend in
 ClickHouse. We recommend trying both to see which is the best fit for your needs.

docs/source/contributor-guide/index.md

@@ -99,6 +99,7 @@ Expression Audits <expression-audits/index>
 Data Source Audits <data-source-audits/index>
 Supported Spark Configurations <spark_configs_support>
 Configuration Conventions <config_conventions>
+Documentation Style Guide <style_guide>
 ```
 
 ```{toctree}