Docs: Add recommendations about Session usage.

docs/source/connecting/connecting.md

@@ -35,9 +35,28 @@ async fn main() -> Result<(), Box<dyn Error>> {
 After successfully connecting to some specified node the driver will fetch topology information about
 other nodes in this cluster and connect to them as well.
 
+## Best practices for using Session
+
+:::{warning}
+Always try to use only a single Session object per apllication because creating them is very expensive!
+:::
+
+The driver maintains its own pool of connections to each node and each connection is capable of handling multiple requests in parallel. Driver will also route requests to nodes / shards that actually own the data (unless the load balancing policy that you use doesn't support it).
+
+For those reasons, we recommend using one instance of `Session` per application.
+
+Creating short-lived `Session`'s (e.g. `Session` per request) is strongly discouraged because it will result in great performance penalties because creating a `Session` is a costly process - it requires estabilishing a lot of TCP connections.
+Creating many `Session`'s in one application (e.g. `Session` per thread / per Tokio task) is also discouraged, because it wastes resources - as mentioned before, `Session` maintains a connection pool itself and can handle parallel queries, so you would be holding a lot of connections unnecessarily.
+
+If you need to share `Session` with different threads / Tokio tasks etc. use `Arc<Session>` - all methods of `Session` take `&self`, so it doesn't hinder the functionality in any way.
+
+## Metadata
+
 The driver refreshes the cluster metadata periodically, which contains information about cluster topology as well as the cluster schema. By default, the driver refreshes the cluster metadata every 60 seconds. 
 However, you can set the `cluster_metadata_refresh_interval` to a non-negative value to periodically refresh the cluster metadata. This is useful when you do not have unexpected amount of traffic or when you have an extra traffic causing topology to change frequently.
 
+## Scylla Cloud Serverless
+
 Scylla Serverless is an elastic and dynamic deployment model. When creating a `Session` you need to
 specify the secure connection bundle as follows:
 

docs/sphinx_preprocessor.py

@@ -1,20 +1,55 @@
 import json
 import sys
 
-def remove_sphinx_markdown(md_file_text):
-    text_split = md_file_text.split("```{eval-rst}")
-
-    result = text_split[0]
+def remove_sphinx_markdown(md_file_text, name):
+    output_lines = []
+    skipped_sections = []
+
+    in_eval_rst = False
+    rst_section_content = []
+
+    for line in md_file_text.splitlines():
+        if in_eval_rst:
+            rst_section_content.append(line)
+            if line.startswith("```"):
+                skipped_sections.append('\n'.join(rst_section_content))
+                rst_section_content = []
+                in_eval_rst = False
+            continue
+
+        if line.startswith("```{eval-rst}"):
+            rst_section_content.append(line)
+            in_eval_rst = True
+            continue
+
+        # mdbook doesn't support other types of admonitions
+        if line == ":::{warning}": 
+            line = '<div class="warning">'
+        elif line == ":::":
+            line = '</div>'
 
-    for i in range(1, len(text_split)):
-        cur_chunk = text_split[i]
-        result += cur_chunk[cur_chunk.find("```") + 3:]
+        if line.startswith(':::'):
+            print(f"Unknown admonition marker in chapter {name}: {line}", file=sys.stderr)
+            sys.exit(1)
 
-    return result
+
+        output_lines.append(line)
+
+    if len(rst_section_content) > 0:
+        print(f'Found unclosed rst section in chapter {name}', file=sys.stderr)
+        sys.exit(1)
+
+    if len(skipped_sections) > 0:
+        print(f"Skipped sections in chapter \"{name}\":", file=sys.stderr)
+        for section in skipped_sections:
+            print(section, file=sys.stderr)
+
+    return '\n'.join(output_lines)
 
 def process_section(section):
     if 'Chapter' in section:
-        section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content'])
+        print(f'Processing chapter {section['Chapter']['name']}', file=sys.stderr)
+        section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content'], section['Chapter']['name'])
         for s in section['Chapter']['sub_items']:
             process_section(s)
 
@@ -23,7 +58,7 @@ def process_section(section):
         if sys.argv[1] == "supports": 
             # then we are good to return an exit status code of 0, since the other argument will just be the renderer's name
             sys.exit(0)
-
+    print('SphinxToMdBook preprocessor running', file=sys.stderr)
     # load both the context and the book representations from stdin
     context, book = json.load(sys.stdin)