From fa0f27069a625057984d1fa58f434ea99b86c83f Mon Sep 17 00:00:00 2001 From: David Garcia Date: Fri, 2 Feb 2024 12:25:53 +0000 Subject: [PATCH] docs: add myst parser chore: add myst parser --- docs/Makefile | 3 ++- docs/pyproject.toml | 2 +- docs/source/conf.py | 23 ++++++++--------------- topics/README.md | 2 +- topics/basics/README.md | 2 +- topics/configuration/README.md | 2 +- topics/dse_features/README.md | 2 +- topics/security/README.md | 2 +- topics/testing/README.md | 2 +- 9 files changed, 17 insertions(+), 23 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 2ba5dd168..6a42bea1e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -28,7 +28,8 @@ setup: $(POETRY) install $(POETRY) update cd .. && doxygen Doxyfile.in - 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 b6fe1c369..c880aecc2 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -9,13 +9,13 @@ breathe="4.35.0" python = "^3.9" pyyaml = "6.0.1" pygments = "2.15.1" -recommonmark = "0.7.1" redirects_cli ="~0.1.2" sphinx-scylladb-theme = "~1.7.2" 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" [tool.poetry.dev-dependencies] pytest = "5.2" diff --git a/docs/source/conf.py b/docs/source/conf.py index 79eff2918..abb7cfad9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,8 +3,6 @@ import re import sys from datetime import date -from recommonmark.transform import AutoStructify -from recommonmark.parser import CommonMarkParser from sphinx_scylladb_theme.utils import multiversion_regex_builder # -- General configuration @@ -32,16 +30,14 @@ 'sphinx_sitemap', 'sphinx_scylladb_theme', 'sphinx_multiversion', - 'breathe' + 'breathe', + 'sphinx_scylladb_markdown' ] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -source_suffix = { - '.rst': 'restructuredtext', - '.md': 'markdown', -} +source_suffix = ['.rst'] autosectionlabel_prefix_document = True # A list of warning types to suppress arbitrary warning messages. @@ -79,6 +75,11 @@ # 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 = [] +suppress_warnings = ["myst.header","myst.xref_missing"] + # -- Options for redirect extension # Read a YAML dictionary of redirections and generate an HTML file for each redirects_file = "_utils/redirections.yaml" @@ -186,14 +187,6 @@ def replace_relative_links(app, docname, source): # Initialize Sphinx def setup(app): - # Setup MarkDown - app.add_source_parser(CommonMarkParser) - app.add_config_value('recommonmark_config', { - 'enable_eval_rst': True, - 'enable_auto_toc_tree': False, - }, True) - app.add_transform(AutoStructify) - # Workaround to replace DataStax links replacements = [ {"http://datastax.github.io/cpp-driver/api/cassandra.h/": "https://cpp-driver.docs.scylladb.com/" + smv_latest_version + "/api"}, diff --git a/topics/README.md b/topics/README.md index 747cff218..a8a02a61d 100644 --- a/topics/README.md +++ b/topics/README.md @@ -309,7 +309,7 @@ with other drivers. Such features can be found (and requested) on our [GH]. [post]: http://www.datastax.com/dev/blog/4-simple-rules-when-using-the-datastax-drivers-for-cassandra [GH]: https://github.com/scylladb/cpp-driver/issues -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/topics/basics/README.md b/topics/basics/README.md index 733532c57..1b3db9b8e 100644 --- a/topics/basics/README.md +++ b/topics/basics/README.md @@ -107,7 +107,7 @@ -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/topics/configuration/README.md b/topics/configuration/README.md index abad588d6..b65bda8d8 100644 --- a/topics/configuration/README.md +++ b/topics/configuration/README.md @@ -457,7 +457,7 @@ expensive or long-running future callbacks are used (via [latency-aware]: http://datastax.github.io/cpp-driver/topics/configuration#token-aware-routing [paging]: http://datastax.github.io/cpp-driver/topics/basics/handling_results#paging -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/topics/dse_features/README.md b/topics/dse_features/README.md index 348c53f38..651bcabdd 100644 --- a/topics/dse_features/README.md +++ b/topics/dse_features/README.md @@ -3,7 +3,7 @@ * [DSE plaintext and GSSAPI authentication](authentication) * [DSE geospatial types](geotypes) -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/topics/security/README.md b/topics/security/README.md index 000168486..7bbe19782 100644 --- a/topics/security/README.md +++ b/topics/security/README.md @@ -138,7 +138,7 @@ int main() { [`cass_cluster_set_credentials()`]: http://datastax.github.io/cpp-driver/api/struct.CassCluster#function-cass_cluster_set_credentials_n -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/topics/testing/README.md b/topics/testing/README.md index fc3368cc8..bc5902f34 100644 --- a/topics/testing/README.md +++ b/topics/testing/README.md @@ -118,7 +118,7 @@ Here are some of the items being scheduled for future enhancements. [build procedures]: http://datastax.github.io/cpp-driver/topics/building#test-dependencies-and-building-tests-not-required -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: