Merge pull request #874 from dgarcia360/docs-myst-parser

docs: add myst parser
scylladb · Jan 23, 2024 · 2af0214 · 2af0214
2 parents 8c20d39 + 631b584
commit 2af0214
Show file tree

Hide file tree

Showing 15 changed files with 25 additions and 29 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/pyproject.toml b/docs/pyproject.toml
@@ -8,13 +8,13 @@ authors = ["ScyllaDB Documentation Contributors"]
 python = "^3.9"
 pyyaml = "6.0.1"
 pygments = "2.15.1"
-recommonmark = "0.7.1"
 redirects_cli ="~0.1.2"
 sphinx-scylladb-theme = "~1.6.1"
 sphinx-sitemap = "2.5.1"
 sphinx-autobuild = "2021.3.14"
 Sphinx = "7.2.6"
 sphinx-multiversion-scylla = "~0.3.1"
+sphinx-scylladb-markdown = "^0.1.2"
 
 [build-system]
 requires = ["poetry>=0.12"]

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -3,7 +3,6 @@
 import sys
 from datetime import date
 
-from recommonmark.transform import AutoStructify
 from pygments.lexers.configs import TOMLLexer
 from pygments.lexers.rust import RustLexer
 from sphinx.highlighting import lexers
@@ -36,14 +35,14 @@
     'sphinx.ext.extlinks',
     'sphinx_sitemap',
     'sphinx_scylladb_theme',
-    'sphinx_multiversion',  # optional
-    'recommonmark',  # optional
+    'sphinx_multiversion',
+    'sphinx_scylladb_markdown'
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = ['.rst', '.md']
+source_suffix = ['.rst']
 autosectionlabel_prefix_document = True
 
 # The master toctree document.
@@ -64,15 +63,9 @@
 
 # Setup Sphinx
 def setup(sphinx):
-    sphinx.add_config_value('recommonmark_config', {
-        'enable_eval_rst': True,
-        'enable_auto_toc_tree': False,
-    }, True)
-    sphinx.add_transform(AutoStructify)
     lexers['rust'] = RustLexer()
     lexers['toml'] = TOMLLexer()
 
-
 # -- Options for not found extension
 
 # Template used to render the 404.html generated by this extension.
@@ -81,6 +74,11 @@ def setup(sphinx):
 # Prefix added to all the URLs generated in the 404 page.
 notfound_urls_prefix = ''
 
+# -- Options for markdown extension
+scylladb_markdown_enable = True
+scylladb_markdown_recommonmark_versions = ['v0.10.1', 'v0.11.1']
+suppress_warnings = ["myst.header","myst.xref_missing"]
+
 # -- Options for multiversion extension
 
 # Whitelist pattern for tags (set to None to ignore all tags)

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/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/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/load-balancing/default-policy.md b/docs/source/load-balancing/default-policy.md
@@ -168,11 +168,9 @@ 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
-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.
+[^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.
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/migration-guides/migration-guides.md b/docs/source/migration-guides/migration-guides.md
@@ -2,7 +2,7 @@
 
 - [Serialization changes in version 0.11](0.11-serialization.md)
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/queries/queries.md b/docs/source/queries/queries.md
@@ -21,7 +21,7 @@ Additionally there is special functionality to enable `USE KEYSPACE` queries:
 
 Queries are fully asynchronous - you can run as many of them in parallel as you wish.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/quickstart/quickstart.md b/docs/source/quickstart/quickstart.md
@@ -11,7 +11,7 @@ Topics Include:
 * [Install Scylla with Docker](scylla-docker.md)
 
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/retry-policy/retry-policy.md b/docs/source/retry-policy/retry-policy.md
@@ -42,7 +42,7 @@ prepared.set_is_idempotent(true);
 # }
 ```
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/speculative-execution/speculative.md b/docs/source/speculative-execution/speculative.md
@@ -15,7 +15,7 @@ Available speculative execution strategies:
 Speculative execution is not enabled by default, and currently only
 non-iter session methods use it.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/source/tracing/tracing.md b/docs/source/tracing/tracing.md
@@ -29,7 +29,7 @@ This is what query execution history was made for.
 It allows to follow what the driver was thinking - all query attempts, retry decisions, speculative executions.
 More information is available in the [Query Execution History](query-history.md) chapter.
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

diff --git a/docs/sphinx_preprocessor.py b/docs/sphinx_preprocessor.py
@@ -2,7 +2,7 @@
 import sys
 
 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]