dnsdist: Automatically generate YAML settings documentation

Signed-off-by: Remi Gacogne <remi.gacogne@powerdns.com>

diff --git a/pdns/dnsdistdist/.gitignore b/pdns/dnsdistdist/.gitignore
index 267c48249f137a8be5d5440bbbbc7f708ea04aaa..5233c2abca969e63bfdd1c49b66a5fd5e6147ca6 100644 (file)
--- a/pdns/dnsdistdist/.gitignore
+++ b/pdns/dnsdistdist/.gitignore
@@ -2,6 +2,7 @@
 *.tar.bz2
 .version
 .venv
+.yaml-settings.stamp
 .dnsdist_history
 /stamp-h1
 /compile

diff --git a/pdns/dnsdistdist/Makefile.am b/pdns/dnsdistdist/Makefile.am
index bf9ebc2ba24042323a9afca09b264153ad14763d..24baff75799f4fa4e0bb19c677cadd9e034b66e5 100644 (file)
--- a/pdns/dnsdistdist/Makefile.am
+++ b/pdns/dnsdistdist/Makefile.am
@@ -655,6 +655,9 @@ $(MANPAGES): %: docs/manpages/%.rst .venv
        $(AM_V_GEN).venv/bin/python -msphinx -b man docs . $<
 endif # if !HAVE_MANPAGES
 
+docs/reference/yaml-settings.rst: dnsdist-settings-documentation-generator.py dnsdist-settings-definitions.yml dnsdist-actions-definitions.yml dnsdist-response-actions-definitions.yml dnsdist-selectors-definitions.yml
+       $(PYTHON) dnsdist-settings-documentation-generator.py .
+
 .venv: docs/requirements.txt
        $(PYTHON) -m venv .venv
        .venv/bin/pip install -U pip setuptools

diff --git a/pdns/dnsdistdist/dnsdist-rust-lib/meson.build b/pdns/dnsdistdist/dnsdist-rust-lib/meson.build
index 824358f089ac82df8816be7256c83a2556016413..9fa0657b4caafbd54a2dec2913079626b389fd7f 100644 (file)
--- a/pdns/dnsdistdist/dnsdist-rust-lib/meson.build
+++ b/pdns/dnsdistdist/dnsdist-rust-lib/meson.build
@@ -2,7 +2,6 @@ sources = files(
   'dnsdist-settings-generator.py',
   '../dnsdist-settings-definitions.yml',
   'dnsdist-configuration-yaml-items-generated-pre-in.cc',
-  'dnsdist-settings-documentation-generator.py',
   'rust-pre-in.rs',
   'rust-middle-in.rs',
   'rust-post-in.rs',

diff --git a/pdns/dnsdistdist/dnsdist-settings-documentation-generator.py b/pdns/dnsdistdist/dnsdist-settings-documentation-generator.py
index 73b8d87e83385fa070ae510f7c8ef6d4e769dfe9..fe30d4267e6b30c011309fd3be566723758d4136 100644 (file)
--- a/pdns/dnsdistdist/dnsdist-settings-documentation-generator.py
+++ b/pdns/dnsdistdist/dnsdist-settings-documentation-generator.py
@@ -1,6 +1,7 @@
 #!/usr/bin/python3
 """Load settings definitions and generates the corresponding documentation."""
 import os
+from pathlib import Path
 import sys
 import tempfile
 import yaml
@@ -185,30 +186,37 @@ def process_selectors_or_actions(def_file, entry_type):
     return output
 
 def main():
-    docs_folder = 'docs/'
+    if len(sys.argv) != 2:
+        print(f'Usage: {sys.argv[0]} <path/to/source/dir>')
+        sys.exit(1)
+
+    source_dir = sys.argv[1]
+    docs_folder = f'{source_dir}/docs/'
     if not os.path.isdir(docs_folder):
         print('Skipping settings documentation generation because the docs/ folder does not exist')
         return
 
     generated_fp = get_temporary_file_for_generated_content(docs_folder)
-    output = process_settings('dnsdist-settings-definitions.yml')
+    output = process_settings(f'{source_dir}/dnsdist-settings-definitions.yml')
     generated_fp.write(output)
     os.rename(generated_fp.name, f'{docs_folder}/reference/yaml-settings.rst')
 
     generated_fp = get_temporary_file_for_generated_content(docs_folder)
-    output = process_selectors_or_actions('dnsdist-actions-definitions.yml', 'action')
+    output = process_selectors_or_actions(f'{source_dir}/dnsdist-actions-definitions.yml', 'action')
     generated_fp.write(output)
     os.rename(generated_fp.name, f'{docs_folder}/reference/yaml-actions.rst')
 
     generated_fp = get_temporary_file_for_generated_content(docs_folder)
-    output = process_selectors_or_actions('dnsdist-response-actions-definitions.yml', 'response-action')
+    output = process_selectors_or_actions(f'{source_dir}/dnsdist-response-actions-definitions.yml', 'response-action')
     generated_fp.write(output)
     os.rename(generated_fp.name, f'{docs_folder}/reference/yaml-response-actions.rst')
 
     generated_fp = get_temporary_file_for_generated_content(docs_folder)
-    output = process_selectors_or_actions('dnsdist-selectors-definitions.yml', 'selector')
+    output = process_selectors_or_actions(f'{source_dir}/dnsdist-selectors-definitions.yml', 'selector')
     generated_fp.write(output)
     os.rename(generated_fp.name, f'{docs_folder}/reference/yaml-selectors.rst')
 
+    Path('.yaml-settings.stamp').touch()
+
 if __name__ == '__main__':
     main()

diff --git a/pdns/dnsdistdist/meson.build b/pdns/dnsdistdist/meson.build
index 70b75f3f2478120fb39f7d23f119b133cca265fc..168ca2c7b9ad2df69f1ec5acc7e823803c2996e3 100644 (file)
--- a/pdns/dnsdistdist/meson.build
+++ b/pdns/dnsdistdist/meson.build
@@ -333,6 +333,29 @@ dep_ffi_interface = declare_dependency(
   sources: [ffi_interface],
 )
 
+py = import('python')
+python = py.find_installation('python3', required: true)
+
+yaml_settings_docs = custom_target(
+  'yaml-settings-docs',
+  command: [
+    python,
+    product_source_dir / 'dnsdist-settings-documentation-generator.py',
+    '@SOURCE_ROOT@',
+  ],
+  depend_files: [
+    'dnsdist-settings-definitions.yml',
+    'dnsdist-actions-definitions.yml',
+    'dnsdist-response-actions-definitions.yml',
+    'dnsdist-selectors-definitions.yml'
+  ],
+  output: '.yaml-settings.stamp',
+)
+
+dep_yaml_settings_docs = declare_dependency(
+  sources: [yaml_settings_docs],
+)
+
 deps = [
   dep_pdns,
   dep_no_config_in_source,
@@ -364,6 +387,7 @@ deps = [
   dep_libbpf,
   dep_libxdp,
   dep_dnsdist_rust_lib,
+  dep_yaml_settings_docs,
 ]
 
 libdnsdist_dnslabeltext_source = src_dir / 'dnslabeltext.rl'
@@ -565,14 +589,13 @@ if get_option('unit-tests')
 endif
 
 # Man-pages.
-py = import('python')
-python = py.find_installation('python3', modules: 'venv', required: false)
+python_venv = py.find_installation('python3', modules: 'venv', required: false)
 
-summary('Python', python.found(), bool_yn: true, section: 'Manual Pages')
+summary('Python with venv', python_venv.found(), bool_yn: true, section: 'Manual Pages')
 
-if get_option('man-pages') and python.found()
-  summary('Path', python.full_path(), section: 'Manual Pages')
-  summary('Version', python.version(), section: 'Manual Pages')
+if get_option('man-pages') and python_venv.found()
+  summary('Path', python_venv.full_path(), section: 'Manual Pages')
+  summary('Version', python_venv.version(), section: 'Manual Pages')
   generated_man_pages = []
   foreach tool, info: tools
     if 'manpages' in info
@@ -597,7 +620,7 @@ if get_option('man-pages') and python.found()
        install: true,
        install_dir: join_paths(get_option('mandir'), 'man1'),
        command: [
-         python,
+         python_venv,
          product_source_dir / docs_dir / 'generate-man-pages.py',
          '--build-root', '@BUILD_ROOT@',
          '--source-root', '@SOURCE_ROOT@',
@@ -711,12 +734,11 @@ install_data(
   follow_symlinks: true
 )
 
-if python.found()
-
+if python_venv.found()
   html_docs = custom_target(
     'html-docs',
     command: [
-        python,
+        python_venv,
         product_source_dir / docs_dir / 'generate-docs.py',
         '--build-root', '@BUILD_ROOT@',
         '--source-root', '@SOURCE_ROOT@',
@@ -738,7 +760,7 @@ if python.found()
 
   pdf_docs = custom_target(
     command: [
-        python,
+        python_venv,
         product_source_dir / docs_dir / 'generate-docs.py',
         '--build-root', '@BUILD_ROOT@',
         '--source-root', '@SOURCE_ROOT@',