docs: add myst parser

docs/Makefile

@@ -25,7 +25,8 @@ setupenv:
 setup:
 	$(POETRY) install
 	$(POETRY) update
-	cp -TLr source $(SOURCEDIR)
+	@if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi
+	cp -RL source/* $(SOURCEDIR)
 	cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'
 
 # Clean commands

docs/pyproject.toml

@@ -8,7 +8,6 @@ authors = ["Java Driver Contributors"]
 python = "^3.9"
 pyyaml = "6.0.1"
 pygments = "2.15.1"
-recommonmark = "0.7.1"
 redirects_cli ="~0.1.3"
 sphinx-scylladb-theme = "~1.7.2"
 sphinx-sitemap = "2.5.1"
@@ -17,6 +16,7 @@ Sphinx = "7.2.6"
 sphinx-multiversion-scylla = "~0.3.1"
 setuptools = "^65.6.3"
 wheel = "^0.38.4"
+sphinx-scylladb-markdown = "^0.1.2"
 
 [build-system]
 requires = ["poetry>=0.12"]

docs/source/conf.py

@@ -1,11 +1,9 @@
 # -*- coding: utf-8 -*-
 
 import os
-from datetime import date
 import re
-from docutils import nodes
-from recommonmark.transform import AutoStructify
-from recommonmark.parser import CommonMarkParser, splitext, urlparse
+from datetime import date
+from pathlib import Path
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 from redirects_cli import cli as redirects_cli
 
@@ -45,6 +43,7 @@
     'sphinx.ext.autosectionlabel',
     'sphinx_scylladb_theme',
     'sphinx_multiversion',
+    'sphinx_scylladb_markdown'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -86,6 +85,23 @@
 # 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 = [
+    'scylla-3.7.2.x',
+    'scylla-3.10.2.x',
+    'scylla-3.11.0.x',
+    'scylla-3.11.2.x',
+    'scylla-4.7.2.x',
+    'scylla-4.10.0.x',
+    'scylla-4.11.1.x',
+    'scylla-4.12.0.x',
+    'scylla-4.13.0.x',
+    'scylla-4.14.1.x',
+    'scylla-4.15.0.x',
+]
+suppress_warnings = ["ref.any", "myst.header","myst.xref_missing"]
+
 # -- Options for multiversion extension
 
 # Whitelist pattern for tags
@@ -149,57 +165,20 @@
 
 # Dictionary of values to pass into the template engine’s context for all pages
 html_context = {'html_baseurl': html_baseurl}
-
-# -- Initialize Sphinx
-
-class CustomCommonMarkParser(CommonMarkParser):
-
-    def visit_document(self, node):
-        pass
-
-    def visit_link(self, mdnode):
-        # Override MarkDownParser to avoid checking if relative links exists
-        ref_node = nodes.reference()
-        destination = mdnode.destination
-        _, ext = splitext(destination)
-
-        url_check = urlparse(destination)
-        scheme_known = bool(url_check.scheme)
-
-        if not scheme_known and ext.replace('.', '') in self.supported:
-            destination = destination.replace(ext, '')
-        ref_node['refuri'] = destination
-        ref_node.line = self._get_line(mdnode)
-        if mdnode.title:
-            ref_node['title'] = mdnode.title
-        next_node = ref_node
-
-        self.current_node.append(next_node)
-        self.current_node = ref_node
-
 def replace_relative_links(app, docname, source):
     result = source[0]
     for key in app.config.replacements:
         result = re.sub(key, app.config.replacements[key], result)
     source[0] = result
 
-
-def build_finished(app, exception):
+def redirect_api_page_to_javadoc(app, exception):
     version_name = os.getenv("SPHINX_MULTIVERSION_NAME", "")
     version_name = "/" + version_name if version_name else ""
     redirect_to = version_name +'/api/index.html'
-    out_file = app.outdir +'/api.html'
-    redirects_cli.create(redirect_to=redirect_to,out_file=out_file)
+    out_file = Path(app.outdir) / 'api.html'
+    redirects_cli.create(redirect_to=redirect_to, out_file=str(out_file))
 
 def setup(app):
-    # Setup Markdown parser
-    app.add_source_parser(CustomCommonMarkParser)
-    app.add_config_value('recommonmark_config', {
-        'enable_eval_rst': True,
-        'enable_auto_toc_tree': False,
-    }, True)
-    app.add_transform(AutoStructify)
-
     # Replace DataStax links
     current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable")
     replacements = {
@@ -208,7 +187,5 @@ def setup(app):
     }
     app.add_config_value('replacements', replacements, True)
     app.connect('source-read', replace_relative_links)
-
-    # Create redirect to JavaDoc API
-    app.connect('build-finished', build_finished)
+    app.connect('build-finished', redirect_api_page_to_javadoc)
 

faq/README.md

@@ -157,9 +157,6 @@ and we've had many reports where the problem turned out to be in user code.
 
 See [Blobs.java] in the `driver-examples` module for some examples and explanations.
 
-[Blobs.java]: https://github.com/datastax/java-driver/tree/3.x/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java
-
-
 ### How do I use the driver in an OSGi application?
 
 Read our [OSGi-specific FAQ section](osgi/) to find out.

faq/osgi/README.md

@@ -1,4 +1,4 @@
-```eval_rst
+```{eval-rst}
 :orphan:
 ```
 ## Frequently Asked Questions - OSGi

manual/README.md

@@ -306,7 +306,7 @@ simply navigate to each sub-directory.
 [NoHostAvailableException]: https://docs.datastax.com/en/drivers/java/3.11/com/datastax/driver/core/exceptions/NoHostAvailableException.html
 [LocalDate]: https://docs.datastax.com/en/drivers/java/3.11/com/datastax/driver/core/LocalDate.html
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

manual/custom_codecs/extras/README.md

@@ -1,4 +1,4 @@
-```eval_rst
+```{eval-rst}
 :orphan:
 ```
 ## Optional codecs

manual/object_mapper/README.md

@@ -21,7 +21,7 @@ See the child pages for more information:
 * [using the mapper](using/)
 * [using custom codecs](custom_codecs/)
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

manual/statements/README.md

@@ -41,7 +41,7 @@ wrap your statements in a custom [StatementWrapper] implementation.
 [execute]:                    https://docs.datastax.com/en/drivers/java/3.11/com/datastax/driver/core/Session.html#execute-com.datastax.driver.core.Statement-
 [executeAsync]:               https://docs.datastax.com/en/drivers/java/3.11/com/datastax/driver/core/Session.html#executeAsync-com.datastax.driver.core.Statement-
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

upgrade_guide/README.md

@@ -827,7 +827,7 @@ exhaustive list of new features in 2.0.
       (`ResultSet#getAvailableWithoutFetching` and `ResultSet#isFullyFetched`)
       as well as a mean to force the pre-fetching of the next page (`ResultSet#fetchMoreResults`).
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob:

upgrade_guide/migrating_from_astyanax/README.md

@@ -9,7 +9,7 @@ See the child pages for more information:
 * [Migrating Astyanax configurations to DataStax Java driver configurations](configuration/)
 * [Querying and retrieving results comparisons.](queries_and_results/)
 
-```eval_rst
+```{eval-rst}
 .. toctree::
    :hidden:
    :glob: