From 9eedcaca09d1bb5bb87452389c1eb9cc1bd9645f Mon Sep 17 00:00:00 2001 From: David Garcia Date: Fri, 2 Feb 2024 13:39:30 +0000 Subject: [PATCH] docs: add myst parser --- docs/Makefile | 3 +- docs/pyproject.toml | 2 +- docs/source/conf.py | 71 +++++++------------ faq/README.md | 3 - faq/osgi/README.md | 2 +- manual/README.md | 2 +- manual/custom_codecs/extras/README.md | 2 +- manual/object_mapper/README.md | 2 +- manual/statements/README.md | 2 +- upgrade_guide/README.md | 2 +- .../migrating_from_astyanax/README.md | 2 +- 11 files changed, 34 insertions(+), 59 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 09ea360f8a3..622f182c8eb 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/pyproject.toml b/docs/pyproject.toml index aafaef2ce6c..7665573fe12 100644 --- a/docs/pyproject.toml +++ b/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"] diff --git a/docs/source/conf.py b/docs/source/conf.py index 25ab16c0781..84e783d2419 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/faq/README.md b/faq/README.md index de17879b763..68e3193e8d1 100644 --- a/faq/README.md +++ b/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. diff --git a/faq/osgi/README.md b/faq/osgi/README.md index 37122b8e957..dde5bee194e 100644 --- a/faq/osgi/README.md +++ b/faq/osgi/README.md @@ -1,4 +1,4 @@ -```eval_rst +```{eval-rst} :orphan: ``` ## Frequently Asked Questions - OSGi diff --git a/manual/README.md b/manual/README.md index 9a50c2d2c38..a7c8f3c9427 100644 --- a/manual/README.md +++ b/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: diff --git a/manual/custom_codecs/extras/README.md b/manual/custom_codecs/extras/README.md index da8187352d5..2a431268b5f 100644 --- a/manual/custom_codecs/extras/README.md +++ b/manual/custom_codecs/extras/README.md @@ -1,4 +1,4 @@ -```eval_rst +```{eval-rst} :orphan: ``` ## Optional codecs diff --git a/manual/object_mapper/README.md b/manual/object_mapper/README.md index 2222f41c4ac..2edbc895eac 100644 --- a/manual/object_mapper/README.md +++ b/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: diff --git a/manual/statements/README.md b/manual/statements/README.md index 7066a73480d..c8a605b5b56 100644 --- a/manual/statements/README.md +++ b/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: diff --git a/upgrade_guide/README.md b/upgrade_guide/README.md index 081cb571c26..6a413a7f547 100644 --- a/upgrade_guide/README.md +++ b/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: diff --git a/upgrade_guide/migrating_from_astyanax/README.md b/upgrade_guide/migrating_from_astyanax/README.md index c899252d63d..f48b08834a4 100644 --- a/upgrade_guide/migrating_from_astyanax/README.md +++ b/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: