docs: update md

scylladb · Dec 19, 2023 · 2b83b50 · 2b83b50
1 parent e5370da
commit 2b83b50
Show file tree

Hide file tree

Showing 39 changed files with 95 additions and 93 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -60,7 +60,7 @@ The documentation book is written using [mdbook](https://github.com/rust-lang/md
 Book source is in `docs/source`\
 This source has to be compatible with `Sphinx` so it might sometimes contain chunks like:
 ````
-```eval_rst
+```{eval-rst}
 something
 ```
 ````

diff --git a/docs/build_book.py b/docs/build_book.py
@@ -2,15 +2,15 @@
 
 # A script which removes sphinx markdown and builds the documentation book
 # It copies all files to working directory, modifies the .md files
-# to remove all ```eval_rst parts and builds the book
+# to remove all ```{eval-rst} parts and builds the book
 # The generated HTML will be in docs/book/scriptbuild/book
 
 import os
 import shutil
 import pathlib
 
 def remove_sphinx_markdown(md_file_text):
-    text_split = md_file_text.split("```eval_rst")
+    text_split = md_file_text.split("```{eval-rst}")
 
     result = text_split[0]
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -77,6 +77,7 @@ def setup(sphinx):
 # -- Options for markdown extension
 scylladb_markdown_enable = True
 scylladb_markdown_recommonmark_versions = ['v0.9.1', 'v0.10.1']
+myst_heading_anchors = 3
 
 # -- Options for multiversion extension
 

diff --git a/docs/source/connecting/authentication.md b/docs/source/connecting/authentication.md
@@ -1,7 +1,8 @@
 # Authentication
 
 Driver supports both authentication by username and password and custom authentication defined by a user.
-###### Important: The default authentication credentials are sent in plain text to the server. For this reason, it is highly recommended that this be used in conjunction with client-to-node encryption (SSL), or in a trusted network environment.
+
+## Important: The default authentication credentials are sent in plain text to the server. For this reason, it is highly recommended that this be used in conjunction with client-to-node encryption (SSL), or in a trusted network environment.
 
 To use the default authentication, specify credentials using the `user` method in `SessionBuilder`:
 
@@ -21,7 +22,7 @@ let session: Session = SessionBuilder::new()
 # Ok(())
 # }
 ```
- ### Custom Authentication
+ ## Custom Authentication
 
 A custom authentication is defined by implementing the `AuthenticatorSession`.
 An `AuthenticatorSession` instance is created per session, so it is also necessary to define a `AuthenticatorProvider` for it.

diff --git a/docs/source/connecting/connecting.md b/docs/source/connecting/connecting.md
@@ -85,7 +85,7 @@ contexts:
 currentContext: default
 ```
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/connecting/tls.md b/docs/source/connecting/tls.md
@@ -5,7 +5,7 @@ It was chosen because [`rustls`](https://github.com/ctz/rustls) doesn't support
 (see [issue](https://github.com/briansmith/webpki/issues/54)), which is a common use case for Scylla.
 
 
-### Enabling feature
+## Enabling feature
 `openssl` is not a pure Rust library so you need enable a feature and install the proper package.
 
 To enable the `tls` feature add in `Cargo.toml`:
@@ -37,7 +37,7 @@ Then install the package with `openssl`:
     pacman -S openssl pkg-config
     ```
 
-### Using TLS
+## Using TLS
 To use tls you will have to create an openssl 
 [`SslContext`](https://docs.rs/openssl/0.10.33/openssl/ssl/struct.SslContext.html)
 and pass it to `SessionBuilder`

diff --git a/docs/source/data-types/data-types.md b/docs/source/data-types/data-types.md
@@ -34,7 +34,7 @@ Database types and their Rust equivalents:
 * `UDT (User defined type)` <----> Custom user structs with macros
 
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/data-types/primitive.md b/docs/source/data-types/primitive.md
@@ -1,6 +1,6 @@
 # Bool, Tinyint, Smallint, Int, Bigint, Float, Double
 
-### Bool
+## Bool
 `Bool` is represented as rust `bool`
 
 ```rust
@@ -26,7 +26,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Tinyint
+## Tinyint
 `Tinyint` is represented as rust `i8`
 
 ```rust
@@ -52,7 +52,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Smallint
+## Smallint
 `Smallint` is represented as rust `i16`
 
 ```rust
@@ -78,7 +78,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Int
+## Int
 `Int` is represented as rust `i32`
 
 ```rust
@@ -104,7 +104,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Bigint
+## Bigint
 `Bigint` is represented as rust `i64`
 
 ```rust
@@ -130,7 +130,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Float 
+## Float 
 `Float` is represented as rust `f32`
 
 ```rust
@@ -156,7 +156,7 @@ if let Some(rows) = session.query("SELECT a FROM keyspace.table", &[]).await?.ro
 # }
 ```
 
-### Double
+## Double
 `Double` is represented as rust `f64`
 
 ```rust

diff --git a/docs/source/execution-profiles/create-and-use.md b/docs/source/execution-profiles/create-and-use.md
@@ -1,6 +1,6 @@
 # Creating a profile and setting it
 
-### Example
+## Example
 To create an `ExecutionProfile` and attach it as default for `Session`:
 ```rust
 # extern crate scylla;
@@ -26,7 +26,7 @@ let session: Session = SessionBuilder::new()
 # }
 ```
 
-### Example
+## Example
 To create an `ExecutionProfile` and attach it to a `Query`:
 ```rust
 # extern crate scylla;
@@ -53,7 +53,7 @@ query2.set_execution_profile_handle(Some(handle));
 # }
 ```
 
-### Example
+## Example
 To create an `ExecutionProfile` based on another profile:
 ```rust
 # extern crate scylla;

diff --git a/docs/source/execution-profiles/execution-profiles.md b/docs/source/execution-profiles/execution-profiles.md
@@ -14,7 +14,7 @@ There are two classes of objects related to execution profiles: `ExecutionProfil
 \
 At any moment, handles [can be remapped](remap.md) to point to another `ExecutionProfile`. This allows convenient switching between workloads for all `Sessions` and/or `Statements` that, for instance, share common characteristics.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/execution-profiles/maximal-example.md b/docs/source/execution-profiles/maximal-example.md
@@ -1,6 +1,6 @@
 # All options supported by a profile
 
-### Example
+## Example
 `ExecutionProfile` supports all the following options:
 ```rust
 # extern crate scylla;

diff --git a/docs/source/execution-profiles/priority.md b/docs/source/execution-profiles/priority.md
@@ -7,7 +7,7 @@ You always have a default execution profile set for the `Session`, either the de
 > `Session`'s default profile < Statement's profile < options set directly on a Statement
 
 
-### Example
+## Example
 Priorities of execution profiles and directly set options:
 ```rust
 # extern crate scylla;

diff --git a/docs/source/execution-profiles/remap.md b/docs/source/execution-profiles/remap.md
@@ -17,7 +17,7 @@ We can also change statement1's handle to handle2, and remap handle1 to profile2
 
 As you can see, profiles are a powerful and convenient way to define and modify your workloads.
 
-### Example
+## Example
 Below, the remaps described above are followed in code.
 ```rust
 # extern crate scylla;

diff --git a/docs/source/index.md b/docs/source/index.md
@@ -3,7 +3,7 @@ This book contains documentation for [scylla-rust-driver](https://github.com/scy
 for the [Scylla](https://scylladb.com) database written in Rust.
 Although optimized for Scylla, the driver is also compatible with [Apache Cassandra®](https://cassandra.apache.org/).
 
-### Other documentation
+## Other documentation
 * [Examples](https://github.com/scylladb/scylla-rust-driver/tree/main/examples)
 * [Rust and Scylla lesson](https://university.scylladb.com/courses/using-scylla-drivers/lessons/rust-and-scylla-2/) on Scylla University
 * [API documentation](https://docs.rs/scylla)

diff --git a/docs/source/load-balancing/default-policy.md b/docs/source/load-balancing/default-policy.md
@@ -4,7 +4,7 @@
 can be configured to be datacenter-aware and token-aware. Datacenter failover
 for queries with non-local consistency mode is also supported.
 
-## Creating a DefaultPolicy
+# Creating a DefaultPolicy
 
 `DefaultPolicy` can be created only using `DefaultPolicyBuilder`. The
 `builder()` method of `DefaultPolicy` returns a new instance of
@@ -31,9 +31,9 @@ let default_policy = DefaultPolicy::builder()
 # }
 ```
 
-### Semantics of `DefaultPolicy`
+## Semantics of `DefaultPolicy`
 
-#### Preferences
+## Preferences
 
 The `preferences` field in `DefaultPolicy` allows the load balancing
 policy to prioritize nodes based on their location. It has three modes:
@@ -60,7 +60,7 @@ false), the default policy will only include local nodes in load balancing
 plans. Remote nodes will be excluded, even if they are alive and available to
 serve requests.
 
-#### Datacenter Failover
+## Datacenter Failover
 
 In the event of a datacenter outage or network failure, the nodes in that
 datacenter may become unavailable, and clients may no longer be able to access
@@ -73,7 +73,7 @@ setting in the builder. When this flag is set, the policy will prefer to return
 alive remote replicas if datacenter failover is permitted and possible due to
 consistency constraints.
 
-#### Token awareness
+## Token awareness
 
 Token awareness refers to a mechanism by which the driver is aware of the token
 range assigned to each node in the cluster. Tokens are assigned to nodes to
@@ -98,7 +98,7 @@ improving throughput.
 Please note that for token awareness to be applied, a statement must be
 prepared before being executed.
 
-### Latency awareness
+## Latency awareness
 
 Latency awareness is a mechanism that penalises nodes whose measured recent
 average latency classifies it as falling behind the others.
@@ -117,7 +117,7 @@ this mechanism may as well worsen latencies and/or throughput.
 >benchmarks prove its beneficial impact on the specific workload's
 >performance. Use with caution.
 
-### Creating a latency aware DefaultPolicy
+## Creating a latency aware DefaultPolicy
 
 ```rust
 # extern crate scylla;
@@ -154,7 +154,7 @@ let default_policy = DefaultPolicy::builder()
 # }
 ```
 
-### Node order in produced plans
+## Node order in produced plans
 
 The DefaultPolicy prefers to return nodes in the following order:
 
@@ -168,11 +168,10 @@ And only if latency awareness is enabled:
 
 If no preferred datacenter is specified, all nodes are treated as local ones.
 
-Replicas in the same priority groups are shuffled[^*]. Non-replicas are randomly
+Replicas in the same priority groups are shuffled[^1]. Non-replicas are randomly
 rotated (similarly to a round robin with a random index).
 
-[^*]: There is an optimisation implemented for LWT requests[^**] that routes them
+[^1]: There is an optimisation implemented for LWT requests that routes them
 to the replicas in the ring order (as it prevents contention due to Paxos conflicts),
-so replicas in that case are not shuffled in groups at all.
-
-[^**]: In order for the optimisation to be applied, LWT statements must be prepared before.
+so replicas in that case are not shuffled in groups at all. 
+In order for the optimisation to be applied, LWT statements must be prepared before.
diff --git a/docs/source/load-balancing/load-balancing.md b/docs/source/load-balancing/load-balancing.md
@@ -115,7 +115,7 @@ node being down or overloaded. The load balancing policy can use this
 information to update its internal state and avoid contacting the same node
 again until it's recovered.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/metrics/metrics.md b/docs/source/metrics/metrics.md
@@ -4,15 +4,15 @@ During operation the driver collects various metrics.
 
 They can be accessed at any moment using `Session::get_metrics()`
 
-### Collected metrics:
+## Collected metrics:
 * Query latencies
 * Total number of nonpaged queries
 * Number of errors during nonpaged queries
 * Total number of paged queries
 * Number of errors during paged queries
 * Number of retries
 
-### Example
+## Example
 ```rust
 # extern crate scylla;
 # use scylla::Session;

diff --git a/docs/source/queries/batch.md b/docs/source/queries/batch.md
@@ -40,7 +40,7 @@ session.batch(&batch, batch_values).await?;
 # }
 ```
 
-### Preparing a batch
+## Preparing a batch
 Instead of preparing each statement individually, it's possible to prepare a whole batch at once:
 
 ```rust
@@ -68,7 +68,7 @@ session.batch(&prepared_batch, batch_values).await?;
 # }
 ```
 
-### Batch options
+## Batch options
 You can set various options by operating on the `Batch` object.\
 For example to change consistency:
 ```rust
@@ -95,7 +95,7 @@ session.batch(&batch, ((), )).await?;
 See [Batch API documentation](https://docs.rs/scylla/latest/scylla/statement/batch/struct.Batch.html)
 for more options
 
-### Batch values
+## Batch values
 Batch takes a tuple of values specified just like in [simple](simple.md) or [prepared](prepared.md) queries.
 
 Length of batch values must be equal to the number of statements in a batch.\
@@ -136,7 +136,7 @@ session.batch(&batch, batch_values).await?;
 For more information about sending values in a statement see [Query values](values.md)
 
 
-### Performance
+## Performance
 Batch statements do not use token/shard aware load balancing, batches are sent to a random node.
 
 Use [prepared queries](prepared.md) for best performance
diff --git a/docs/source/queries/lwt.md b/docs/source/queries/lwt.md
@@ -3,7 +3,7 @@
 A lightweight transaction query can be expressed just like any other query, via `Session`, with the notable difference of having an additional consistency level parameter - the `serial_consistency_level`.
 
 
-### Format of the query
+## Format of the query
 A lightweight transaction query is not a separate type - it can be expressed just like any other queries: via `SimpleQuery`, `PreparedStatement`, batches, and so on. The difference lays in the query string itself - when it contains a condition (e.g. `IF NOT EXISTS`), it becomes a lightweight transaction. It's important to remember that CQL specification requires a separate, additional consistency level to be defined for LWT queries - `serial_consistency_level`. The serial consistency level can only be set to two values: `SerialConsistency::Serial` or `SerialConsistency::LocalSerial`. The "local" variant makes the transaction consistent only within the same datacenter. For convenience, Scylla Rust Driver sets the default consistency level to `LocalSerial`, as it's more commonly used. For cross-datacenter consistency, please remember to always override the default with `SerialConsistency::Serial`.
 ```rust
 # extern crate scylla;