diff --git a/.gitignore b/.gitignore index 1a44f3ce64..c271273ef2 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ test/*/*.reject .vscode docs/_build docs/poetry.lock +docs/_data/*.yaml compile_commands.json .ccls-cache/ .mypy_cache diff --git a/docs/Makefile b/docs/Makefile index ed0f982ce8..4f07799f23 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -48,6 +48,7 @@ pristine: clean .PHONY: clean clean: rm -rf $(BUILDDIR)/* + rm -rf _data/* rm -f poetry.lock # Generate output commands @@ -87,7 +88,6 @@ redirects: setup @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - # Preview commands .PHONY: preview preview: setup @@ -107,3 +107,4 @@ test: setup .PHONY: linkcheck linkcheck: setup $(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck + diff --git a/docs/_ext/scylladb_cc_properties.py b/docs/_ext/scylladb_cc_properties.py new file mode 100644 index 0000000000..6b432fd516 --- /dev/null +++ b/docs/_ext/scylladb_cc_properties.py @@ -0,0 +1,50 @@ +import os +import re +import yaml +from sphinx.application import Sphinx + +CONFIG_FILE_PATH = '../db/config.cc' +DESTINATION_PATH = '_data/db_config.yaml' + +def create_yaml_file(destination, data): + current_data = None + + try: + with open(destination, 'r') as file: + current_data = yaml.safe_load(file) + except FileNotFoundError: + pass + + if current_data != data: + os.makedirs(os.path.dirname(destination), exist_ok=True) + with open(destination, 'w') as file: + yaml.dump(data, file) + +def parse_db_properties(config_file): + with open(config_file, 'r') as file: + content = file.read() + + pattern = r',\s*(\w+)\(this,\s*"(\w+)",\s*(?:liveness::(\w+),\s*)?value_status::(\w+),\s*([^,]+),\s*"([^"]+)"\)' + matches = re.findall(pattern, content) + + properties = [] + for match in matches: + property_data = { + "name": match[1].strip(), + "value_status": match[3].strip(), + "default": match[4].strip(), + "liveness": 'True' if match[2] else 'False', + "description": match[5].strip().replace('\n', '
') + } + properties.append(property_data) + + return properties + +def generate_cc_docs(app: Sphinx): + dest_path = os.path.join(app.builder.srcdir, DESTINATION_PATH) + parsed_properties = parse_db_properties(CONFIG_FILE_PATH) + create_yaml_file(dest_path, parsed_properties) + + +def setup(app: Sphinx): + app.connect("builder-inited", generate_cc_docs) diff --git a/docs/_templates/db_config.tmpl b/docs/_templates/db_config.tmpl new file mode 100644 index 0000000000..a08ab18fc7 --- /dev/null +++ b/docs/_templates/db_config.tmpl @@ -0,0 +1,23 @@ +.. -*- mode: rst -*- + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Name + - Description +{% for item in data %} + + * - .. _config_{{ item.name }}: + + ``{{ item.name }}`` + - **Default value:** ``{{ item.default }}`` + + **Value status:** {{ item.value_status }} + + **Liveness:** {{ item.liveness }} + + .. raw:: html + +

{{item.description}}

+{% endfor %} diff --git a/docs/conf.py b/docs/conf.py index 2d9ba529ed..51507bca52 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,6 +7,7 @@ from datetime import date from sphinx_scylladb_theme.utils import multiversion_regex_builder from recommonmark.transform import AutoStructify +sys.path.insert(0, os.path.abspath('./_ext')) sys.path.insert(0, os.path.abspath("..")) # -- Global variables @@ -36,6 +37,8 @@ extensions = [ "sphinx_scylladb_theme", "sphinx_multiversion", # optional "recommonmark", # optional + "sphinxcontrib.datatemplates", + "scylladb_cc_properties", ] # The suffix(es) of source filenames. @@ -95,6 +98,7 @@ smv_outputdir_format = "{ref.name}" # The theme to use for pages. html_theme = "sphinx_scylladb_theme" +templates_path = ['_templates', ] # These folders are copied to the documentation's HTML output html_static_path = ['_static'] @@ -138,7 +142,6 @@ html_baseurl = BASE_URL # Dictionary of values to pass into the template engine’s context for all pages html_context = {"html_baseurl": html_baseurl} - # -- Initialize Sphinx ---------------------------------------------- def setup(sphinx): warnings.filterwarnings( diff --git a/docs/pyproject.toml b/docs/pyproject.toml index a1c60c0b4a..f1f2c158bc 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -16,6 +16,7 @@ Sphinx = "4.3.2" sphinx-multiversion-scylla = "~0.2.10" sphinx-markdown-tables = "0.0.15" redirects_cli ="~0.1.2" +sphinxcontrib-datatemplates = "^0.9.2" [build-system] requires = ["poetry>=0.12"] diff --git a/docs/reference/db-config.rst b/docs/reference/db-config.rst new file mode 100644 index 0000000000..67ff907253 --- /dev/null +++ b/docs/reference/db-config.rst @@ -0,0 +1,8 @@ +:orphan: + +======================= +db/config.cc properties +======================= + +.. datatemplate:yaml:: ../_data/db_config.yaml + :template: db_config.tmpl