docs: Autogenerate db/config.cc docs

Update layout

docs: remove output param

docs: generate cc properties on build

docs: track cc file on change

rm: note dependency

docs: clean _data

Fixes #8424.

Closes #14973

.gitignore

@@ -28,6 +28,7 @@ test/*/*.reject
 .vscode
 docs/_build
 docs/poetry.lock
+docs/_data/*.yaml
 compile_commands.json
 .ccls-cache/
 .mypy_cache

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
+

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', '<br />')
+        }
+        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)

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
+
+          <p>{{item.description}}</p>
+{% endfor %}

docs/conf.py

@@ -7,6 +7,7 @@
 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 @@
     "sphinx_scylladb_theme",
     "sphinx_multiversion",  # optional
     "recommonmark",  # optional
+    "sphinxcontrib.datatemplates",
+    "scylladb_cc_properties",
 ]
 
 # The suffix(es) of source filenames.
@@ -95,6 +98,7 @@
 
 # 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 @@
 # 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(

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"]

docs/reference/db-config.rst

@@ -0,0 +1,8 @@
+:orphan:
+
+=======================
+db/config.cc properties
+=======================
+
+.. datatemplate:yaml:: ../_data/db_config.yaml
+  :template: db_config.tmpl