diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml new file mode 100644 index 0000000000..b560c7ca3c --- /dev/null +++ b/.github/workflows/docs-pages.yaml @@ -0,0 +1,45 @@ +name: "Docs / Publish" +# For more information, +# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows + +on: + push: + branches: + - scylla-3.x + - 'branch-**' + paths: + - 'docs/**' + - 'faq/**' + - 'manual/**' + - 'changelog/**' + - 'upgrade_guide/**' + workflow_dispatch: + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + ref: ${{ github.event.repository.default_branch }} + persist-credentials: false + fetch-depth: 0 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + - name: Set up JDK 1.8 + uses: actions/setup-java@v1 + with: + java-version: 1.8 + - name: Set up env + run: make -C docs setupenv + - name: Build redirects + run: make -C docs redirects + - name: Build docs + run: make -C docs multiversion + - name: Deploy docs to GitHub Pages + run: ./docs/_utils/deploy.sh + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml new file mode 100644 index 0000000000..a8dd1276c2 --- /dev/null +++ b/.github/workflows/docs-pr.yaml @@ -0,0 +1,36 @@ +name: "Docs / Build PR" +# For more information, +# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows + +on: + pull_request: + branches: + - scylla-4.x + paths: + - 'docs/**' + - 'faq/**' + - 'manual/**' + - 'changelog/**' + - 'upgrade_guide/**' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + persist-credentials: false + fetch-depth: 0 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + - name: Set up JDK 1.8 + uses: actions/setup-java@v1 + with: + java-version: 1.8 + - name: Set up env + run: make -C docs setupenv + - name: Build docs + run: make -C docs test diff --git a/README-dev.md b/README-dev.md new file mode 100644 index 0000000000..71234332fc --- /dev/null +++ b/README-dev.md @@ -0,0 +1,16 @@ +# Building the docs + +## Prerequisites + +To build the documentation of this project, you need a UNIX-based operating system. Windows is not fully supported as it does not support symlinks. + +You also need the following software installed to generate the reference documentation of the driver: + +- Java JDK 8 or higher +- Maven + +Once you have installed the above software, you can build and preview the documentation by following the steps outlined in the `Quickstart guide `_. + +## Custom commands + +To generate the reference documentation of the driver, run the command `make javadoc`. This command generates the reference documentation using the Javadoc tool in the `_build/dirhtml//api` directory. diff --git a/docs.yaml b/docs.yaml deleted file mode 100644 index 7c679a0f47..0000000000 --- a/docs.yaml +++ /dev/null @@ -1,60 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -title: Java Driver -summary: Java Driver for Apache Cassandra® -homepage: http://docs.datastax.com/en/developer/java-driver -theme: datastax -sections: - - title: Manual - prefix: /manual - sources: - - type: markdown - files: 'manual/**/*.md' - - title: Reference configuration - prefix: /manual/core/configuration/reference - sources: - - type: rst - files: 'manual/core/configuration/reference/*.rst' - - title: Changelog - prefix: /changelog - sources: - - type: markdown - files: 'changelog/**/*.md' - - title: Upgrading - prefix: /upgrade_guide - sources: - - type: markdown - files: 'upgrade_guide/**/*.md' - - title: FAQ - prefix: /faq - sources: - - type: markdown - files: 'faq/**/*.md' -links: - - title: Code - href: https://github.com/datastax/java-driver/ - - title: Docs - href: http://docs.datastax.com/en/developer/java-driver - - title: Issues - href: https://datastax-oss.atlassian.net/browse/JAVA/ - - title: Mailing List - href: https://groups.google.com/a/lists.datastax.com/forum/#!forum/java-driver-user - - title: Releases - href: https://github.com/datastax/java-driver/releases -api_docs: - 4.0: http://docs.datastax.com/en/drivers/java/4.0 diff --git a/docs/Makefile b/docs/Makefile index 2cebd73728..1dde91348b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,89 +1,105 @@ # You can set these variables from the command line. -POETRY = $(HOME)/.poetry/bin/poetry -SPHINXOPTS = +POETRY = poetry +SPHINXOPTS = -j auto SPHINXBUILD = $(POETRY) run sphinx-build PAPER = BUILDDIR = _build -SOURCE_DIR = _source +SOURCEDIR = _source -# Internal variables. +# Internal variables PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR) +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going - -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) .PHONY: all all: dirhtml +# Setup commands +.PHONY: setupenv +setupenv: + pip install -q poetry + +.PHONY: setup +setup: + $(POETRY) install + $(POETRY) update + @if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi + cp -RL source/* $(SOURCEDIR) + cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';' + +# Clean commands .PHONY: pristine pristine: clean git clean -dfX -.PHONY: setup -setup: - ./_utils/setup.sh - cp -TLr source $(SOURCE_DIR) - cd $(SOURCE_DIR) && find . -name README.md -execdir mv '{}' index.md ';' .PHONY: clean clean: rm -rf $(BUILDDIR)/* - rm -rf $(SOURCE_DIR)/* - -.PHONY: preview -preview: setup - cd .. && ./docs/_utils/javadoc.sh - $(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 + rm -rf $(SOURCEDIR)/* + rm -f poetry.lock +# Generate output commands .PHONY: dirhtml dirhtml: setup + @$(javadoc) $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -.PHONY: singlehtml -singlehtml: setup - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml +.PHONY: javadoc +javadoc: setup + cd .. && ./docs/_utils/javadoc.sh @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." +.PHONY: multiversion +multiversion: setup + $(POETRY) run ./_utils/multiversion.sh + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + .PHONY: epub -epub: setup +epub: setup $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." .PHONY: epub3 -epub3: setup +epub3:setup $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 @echo @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." .PHONY: dummy -dummy: setup +dummy: setup $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy @echo @echo "Build finished. Dummy builder generates no files." -.PHONY: linkcheck -linkcheck: setup - $(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck - -.PHONY: multiversion -multiversion: setup - @mkdir -p $(HOME)/.cache/pypoetry/virtualenvs - $(POETRY) run ./_utils/multiversion.sh - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +# Preview commands +.PHONY: preview +preview: setup + $(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --re-ignore 'api/*' .PHONY: multiversionpreview multiversionpreview: multiversion - $(POETRY) run python3 -m http.server 5500 --directory $(BUILDDIR)/dirhtml + $(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml + +.PHONY: redirects +redirects: setup + $(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +# Test commands .PHONY: test test: setup $(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." \ No newline at end of file + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: linkcheck +linkcheck: setup + $(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh index d7669dd1ed..0c39996f68 100755 --- a/docs/_utils/javadoc.sh +++ b/docs/_utils/javadoc.sh @@ -1,7 +1,7 @@ #!/bin/bash # Install dependencies -mvn install -DskipTests +mvn install -DskipTests -T 1C # Define output folder OUTPUT_DIR="docs/_build/dirhtml/api" @@ -11,7 +11,7 @@ if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then fi # Generate javadoc -mvn javadoc:javadoc +mvn javadoc:javadoc -T 1C [ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR mkdir -p "$OUTPUT_DIR" mv -f core/target/site/apidocs/* $OUTPUT_DIR diff --git a/docs/_utils/multiversion.sh b/docs/_utils/multiversion.sh index 19270f3293..89895a896c 100755 --- a/docs/_utils/multiversion.sh +++ b/docs/_utils/multiversion.sh @@ -1,5 +1,5 @@ #! /bin/bash cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \ - --pre-build './docs/_utils/javadoc.sh' \ - --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'" + --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'" \ + --post-build './docs/_utils/javadoc.sh' diff --git a/docs/_utils/redirections.yaml b/docs/_utils/redirections.yaml deleted file mode 100644 index 0e5f1ff9e0..0000000000 --- a/docs/_utils/redirections.yaml +++ /dev/null @@ -1 +0,0 @@ -api: /api/overview-summary.html diff --git a/docs/_utils/redirects.yaml b/docs/_utils/redirects.yaml new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/_utils/setup.sh b/docs/_utils/setup.sh deleted file mode 100755 index b8f50243e4..0000000000 --- a/docs/_utils/setup.sh +++ /dev/null @@ -1,11 +0,0 @@ -#! /bin/bash - -if pwd | egrep -q '\s'; then - echo "Working directory name contains one or more spaces." - exit 1 -fi - -which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; } -which poetry || curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/1.1.3/get-poetry.py | python3 - && source ${HOME}/.poetry/env -poetry install -poetry update diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 170bdbf936..7665573fe1 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -5,18 +5,18 @@ description = "ScyllaDB Java Driver" authors = ["Java Driver Contributors"] [tool.poetry.dependencies] -python = "^3.7" -pyyaml = "5.3" -pygments = "2.2.0" -recommonmark = "0.5.0" -sphinx-scylladb-theme = "~1.0.0" -sphinx-sitemap = "2.1.0" -sphinx-autobuild = "0.7.1" -Sphinx = "2.4.4" -sphinx-multiversion-scylla = "~0.2.6" - -[tool.poetry.dev-dependencies] -pytest = "5.2" +python = "^3.9" +pyyaml = "6.0.1" +pygments = "2.15.1" +redirects_cli ="~0.1.3" +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" +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/_templates/notice.html b/docs/source/_templates/notice.html new file mode 100644 index 0000000000..c65ea8d802 --- /dev/null +++ b/docs/source/_templates/notice.html @@ -0,0 +1,5 @@ +
+

ScyllaDB Java Driver is available under the Apache v2 License. + ScyllaDB Java Driver is a fork of DataStax Java Driver. + See Copyright here.

+
diff --git a/docs/source/conf.py b/docs/source/conf.py index 71dbea8883..f113e7a3b7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,19 +1,37 @@ # -*- coding: utf-8 -*- import os -import sys -from datetime import date -import yaml import re -from docutils import nodes -from sphinx.util import logging -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 -# -- General configuration ------------------------------------------------ +# -- General configuration -# Add any Sphinx extension'¡' module names here, as strings. They can be +# Build documentation for the following tags and branches +TAGS = [] +BRANCHES = [ + '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' +] +# Set the latest version. +LATEST_VERSION = 'scylla-4.15.0.x' +# Set which versions are not released yet. +UNSTABLE_VERSIONS = [] +# Set which versions are deprecated +DEPRECATED_VERSIONS = [] + +# Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ @@ -21,11 +39,16 @@ 'sphinx.ext.mathjax', 'sphinx.ext.githubpages', 'sphinx.ext.extlinks', + 'sphinx_sitemap', 'sphinx.ext.autosectionlabel', 'sphinx_scylladb_theme', 'sphinx_multiversion', + 'sphinx_scylladb_markdown' ] +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # @@ -35,50 +58,6 @@ } autosectionlabel_prefix_document = True -class CustomCommonMarkParser(CommonMarkParser): - - def visit_document(self, node): - pass - - def visit_link(self, mdnode): - # Override 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 setup(app): - 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 - replacements = {r'https://docs.datastax.com/en/drivers/java\/(.*?)\/': "https://java-driver.docs.scylladb.com/stable/api/"} - app.add_config_value('replacements', replacements, True) - app.connect('source-read', replace_relative_links) - # The master toctree document. master_doc = 'contents' @@ -98,7 +77,7 @@ def setup(app): # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True -# -- Options for not found extension ------------------------------------------- +# -- Options for not found extension # Template used to render the 404.html generated by this extension. notfound_template = '404.html' @@ -106,32 +85,45 @@ def setup(app): # Prefix added to all the URLs generated in the 404 page. notfound_urls_prefix = '' -# -- Options for redirect extension --------------------------------------- - -# Read a YAML dictionary of redirections and generate an HTML file for each -redirects_file = "_utils/redirections.yaml" +# -- 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","autosectionlabel"] -# -- Options for multiversion extension ---------------------------------- +# -- Options for multiversion extension -# Whitelist pattern for tags (set to None to ignore all tags) -TAGS = [] +# Whitelist pattern for tags smv_tag_whitelist = multiversion_regex_builder(TAGS) -# Whitelist pattern for branches (set to None to ignore all branches) -BRANCHES = ['scylla-3.x', 'scylla-3.7.2.x', 'scylla-3.10.2.x'] +# Whitelist pattern for branches smv_branch_whitelist = multiversion_regex_builder(BRANCHES) # Defines which version is considered to be the latest stable version. # Must be listed in smv_tag_whitelist or smv_branch_whitelist. -smv_latest_version = 'scylla-3.10.2.x' +smv_latest_version = LATEST_VERSION smv_rename_latest_version = 'stable' # Whitelist pattern for remotes (set to None to use local branches only) -smv_remote_whitelist = r"^origin$" +smv_remote_whitelist = r'^origin$' # Pattern for released versions smv_released_pattern = r'^tags/.*$' # Format for versioned output directories inside the build directory smv_outputdir_format = '{ref.name}' +# -- Options for sitemap extension -# -- Options for HTML output ---------------------------------------------- +sitemap_url_scheme = "/stable/{link}" + +# -- Options for HTML output # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. @@ -148,8 +140,11 @@ def setup(app): 'github_repository': 'scylladb/java-driver', 'github_issues_repository': 'scylladb/java-driver', 'hide_edit_this_page_button': 'false', - 'hide_sidebar_index': 'false', + 'hide_feedback_buttons': 'false', + 'versions_unstable': UNSTABLE_VERSIONS, + 'versions_deprecated': DEPRECATED_VERSIONS, 'hide_version_dropdown': ['scylla-3.x'], + 'skip_warnings': 'document_has_underscores' } # If not None, a 'Last updated on:' timestamp is inserted at every page @@ -170,3 +165,26 @@ def setup(app): # Dictionary of values to pass into the template engine’s context for all pages html_context = {'html_baseurl': html_baseurl} +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 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 = Path(app.outdir) / 'api.html' + redirects_cli.create(redirect_to=redirect_to, out_file=str(out_file)) + +def setup(app): + # Replace DataStax links + current_slug = os.getenv("SPHINX_MULTIVERSION_NAME", "stable") + replacements = { + r'docs.datastax.com/en/drivers/java\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/api/", + r'java-driver.docs.scylladb.com\/(.*?)\/': "java-driver.docs.scylladb.com/" + current_slug + "/" + } + app.add_config_value('replacements', replacements, True) + app.connect('source-read', replace_relative_links) + app.connect('build-finished', redirect_api_page_to_javadoc) diff --git a/manual/README.md b/manual/README.md index 8411eb586f..582e5264b1 100644 --- a/manual/README.md +++ b/manual/README.md @@ -34,7 +34,7 @@ Common topics: * [Case sensitivity](case_sensitivity/) * [OSGi](osgi/) -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/core/README.md b/manual/core/README.md index f7e26b4d16..bce32f27b0 100644 --- a/manual/core/README.md +++ b/manual/core/README.md @@ -351,7 +351,7 @@ for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) { [CASSANDRA-10145]: https://issues.apache.org/jira/browse/CASSANDRA-10145 -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/core/configuration/README.md b/manual/core/configuration/README.md index c5c23d2ea8..0c54988cd7 100644 --- a/manual/core/configuration/README.md +++ b/manual/core/configuration/README.md @@ -556,7 +556,7 @@ config.getDefaultProfile().getInt(MyCustomOption.AWESOMENESS_FACTOR); [HOCON]: https://github.com/typesafehub/config/blob/master/HOCON.md [API conventions]: ../../api_conventions -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/core/metadata/README.md b/manual/core/metadata/README.md index 0eb6a0904a..409ec1b0ac 100644 --- a/manual/core/metadata/README.md +++ b/manual/core/metadata/README.md @@ -79,7 +79,7 @@ refreshed. See the [Performance](../performance/#debouncing) page for more detai [Metadata]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Metadata.html [Node]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/metadata/Node.html -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/core/statements/README.md b/manual/core/statements/README.md index 8a4c225613..08946bafb3 100644 --- a/manual/core/statements/README.md +++ b/manual/core/statements/README.md @@ -83,7 +83,7 @@ can create execution profiles to capture common combinations of those options). [execute]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#execute-com.datastax.oss.driver.api.core.cql.Statement- [executeAsync]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/Session.html#executeAsync-com.datastax.oss.driver.api.core.cql.Statement- -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/developer/README.md b/manual/developer/README.md index 73e6cf243f..63c1ea9d52 100644 --- a/manual/developer/README.md +++ b/manual/developer/README.md @@ -37,7 +37,7 @@ from lowest to highest level: If you're reading this on GitHub, the `.nav` file in each directory contains a suggested order. -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/developer/common/README.md b/manual/developer/common/README.md index 489a46fdc1..cda61f3f18 100644 --- a/manual/developer/common/README.md +++ b/manual/developer/common/README.md @@ -27,7 +27,7 @@ This covers utilities or concept that are shared throughout the codebase: * the [event bus](event_bus/) is used to decouple some of the internal components through asynchronous messaging. -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/mapper/README.md b/manual/mapper/README.md index f77daf6c08..a29f8e023c 100644 --- a/manual/mapper/README.md +++ b/manual/mapper/README.md @@ -172,7 +172,7 @@ You can decide which logs to enable using the standard SLF4J mechanisms (categor addition, if you want no logs at all, it's possible to entirely remove them from the generated code with the Java compiler option `-Acom.datastax.oss.driver.mapper.logs.enabled=false`. -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/mapper/config/README.md b/manual/mapper/config/README.md index b974e5cce0..0154b03dea 100644 --- a/manual/mapper/config/README.md +++ b/manual/mapper/config/README.md @@ -133,7 +133,7 @@ You will find the generated files in `build/generated/sources/annotationProcesso * [Java 14 records](record/) * [Scala](scala/) -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/mapper/daos/README.md b/manual/mapper/daos/README.md index 705f1bc912..673583afd1 100644 --- a/manual/mapper/daos/README.md +++ b/manual/mapper/daos/README.md @@ -173,7 +173,7 @@ To control how the hierarchy is scanned, annotate interfaces with [@HierarchySca [@HierarchyScanStrategy]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/mapper/annotations/HierarchyScanStrategy.html [Entity Inheritance]: ../entities/#inheritance -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/mapper/daos/getentity/README.md b/manual/mapper/daos/getentity/README.md index abb7cb076c..de9a530b55 100644 --- a/manual/mapper/daos/getentity/README.md +++ b/manual/mapper/daos/getentity/README.md @@ -108,7 +108,7 @@ The method can return: * a single entity instance. If the argument is a result set type, the generated code will extract the first row and convert it, or return `null` if the result set is empty. - ````java + ```java @GetEntity Product asProduct(Row row); diff --git a/manual/query_builder/README.md b/manual/query_builder/README.md index 037fefc81b..f8897a25c8 100644 --- a/manual/query_builder/README.md +++ b/manual/query_builder/README.md @@ -213,7 +213,7 @@ For a complete tour of the API, browse the child pages in this manual: [DseQueryBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseQueryBuilder.html [DseSchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/dse/driver/api/querybuilder/DseSchemaBuilder.html -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: diff --git a/manual/query_builder/schema/README.md b/manual/query_builder/schema/README.md index 0fe8edb8a6..9443ae4262 100644 --- a/manual/query_builder/schema/README.md +++ b/manual/query_builder/schema/README.md @@ -65,7 +65,7 @@ element type: [SchemaBuilder]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/querybuilder/SchemaBuilder.html -```eval_rst +```{eval-rst} .. toctree:: :hidden: :glob: