From: Remi Gacogne Date: Mon, 2 Jun 2025 13:40:44 +0000 (+0200) Subject: dnsdist: Automatically generate YAML settings documentation X-Git-Tag: dnsdist-2.0.0-beta1~39^2~10 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=829738818ad84ee1055cda2f1320af9092d31e71;p=thirdparty%2Fpdns.git dnsdist: Automatically generate YAML settings documentation Signed-off-by: Remi Gacogne --- diff --git a/pdns/dnsdistdist/.gitignore b/pdns/dnsdistdist/.gitignore index 267c48249f..5233c2abca 100644 --- 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 bf9ebc2ba2..24baff7579 100644 --- 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 824358f089..9fa0657b4c 100644 --- 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 73b8d87e83..fe30d4267e 100644 --- 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]} ') + 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 70b75f3f24..168ca2c7b9 100644 --- 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@',