From 631b58436eb33b6cd65333b1bc7cd84bc34df94a Mon Sep 17 00:00:00 2001 From: David Garcia Date: Tue, 16 Jan 2024 10:49:00 +0000 Subject: [PATCH] docs: add myst parser --- CONTRIBUTING.md | 2 +- docs/pyproject.toml | 2 +- docs/source/conf.py | 18 ++++++++---------- docs/source/connecting/connecting.md | 2 +- docs/source/data-types/data-types.md | 2 +- .../execution-profiles/execution-profiles.md | 2 +- docs/source/load-balancing/default-policy.md | 10 ++++------ docs/source/load-balancing/load-balancing.md | 2 +- .../migration-guides/migration-guides.md | 2 +- docs/source/queries/queries.md | 2 +- docs/source/quickstart/quickstart.md | 2 +- docs/source/retry-policy/retry-policy.md | 2 +- .../speculative-execution/speculative.md | 2 +- docs/source/tracing/tracing.md | 2 +- docs/sphinx_preprocessor.py | 2 +- 15 files changed, 25 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 174c11cb8b..fb575faed0 100644 --- 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 index 2a2ff113a1..afb7846d9a 100644 --- 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 index 9e2215e647..0d074ec1cd 100644 --- 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 index 1522cb2571..378cbd61b6 100644 --- 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 index 6fe7c70e07..75daf08a76 100644 --- 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 index 6044d772c0..6f36726aff 100644 --- 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 index c94a629d04..4f8310a36f 100644 --- 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 index cf5c699baf..5fc8a069c1 100644 --- 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 index 554af6e41a..86887a64c9 100644 --- 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 index fa1259f1a4..b75810d0ad 100644 --- 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 index dca0049ada..b544aef743 100644 --- 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 index b7be89a2c9..b4859b0c89 100644 --- 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 index 34d440f2ac..d6e2ae0422 100644 --- 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 index dbf50ce2c0..75ea2d5fee 100644 --- 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 index fc85848e11..3331952ecc 100644 --- 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]