Hotdoc: use template for Commands.md instead of generating the entire file (#8154)

* doc: fix hotdoc misuse for dynamically generated content

hotdoc has a native include feature for including files inline. Use this
to generate one file for each dynamically generated code block, and
include that file in Commands.md; see:
https://hotdoc.github.io/syntax-extensions.html#smart-file-inclusion-syntax

This permits us to move back to using the in-tree version of the hotdoc
*.md sources, thus fixing the incorrect inclusion of "builddir/" in the
"Edit on github" links which resulted from using copies as the source.

Fixes #8061

* doc: call the dummy file a "stamp" as it is a better known term

docs/markdown/Commands.md

@@ -16,15 +16,11 @@ For the full list of all available options for a specific command use the follow
 
 ### configure
 
-```
+{{ configure_usage.inc }}
-{{ cmd_help['configure']['usage'] }}
-```
 
 Changes options of a configured meson project.
 
-```
+{{ configure_arguments.inc }}
-{{ cmd_help['configure']['arguments'] }}
-```
 
 Most arguments are the same as in [`setup`](#setup).
 
@@ -46,15 +42,11 @@ meson configure builddir -Doption=new_value
 
 *(since 0.54.0)*
 
-```
+{{ compile_usage.inc }}
-{{ cmd_help['compile']['usage'] }}
-```
 
 Builds a default or a specified target of a configured meson project.
 
-```
+{{ compile_arguments.inc }}
-{{ cmd_help['compile']['arguments'] }}
-```
 
 `--verbose` argument is available since 0.55.0.
 
@@ -115,15 +107,11 @@ meson compile coverage-html
 
 *(since 0.52.0)*
 
-```
+{{ dist_usage.inc }}
-{{ cmd_help['dist']['usage'] }}
-```
 
 Generates a release archive from the current source tree.
 
-```
+{{ dist_arguments.inc }}
-{{ cmd_help['dist']['arguments'] }}
-```
 
 See [notes about creating releases](Creating-releases.md) for more info.
 
@@ -138,15 +126,11 @@ meson dist -C builddir
 
 *(since 0.45.0)*
 
-```
+{{ init_usage.inc }}
-{{ cmd_help['init']['usage'] }}
-```
 
 Creates a basic set of build files based on a template.
 
-```
+{{ init_arguments.inc }}
-{{ cmd_help['init']['arguments'] }}
-```
 
 #### Examples:
 
@@ -157,15 +141,11 @@ meson init -C sourcedir
 
 ### introspect
 
-```
+{{ introspect_usage.inc }}
-{{ cmd_help['introspect']['usage'] }}
-```
 
 Displays information about a configured meson project.
 
-```
+{{ introspect_arguments.inc }}
-{{ cmd_help['introspect']['arguments'] }}
-```
 
 #### Examples:
 
@@ -178,15 +158,11 @@ meson introspect builddir
 
 *(since 0.47.0)*
 
-```
+{{ install_usage.inc }}
-{{ cmd_help['install']['usage'] }}
-```
 
 Installs the project to the prefix specified in [`setup`](#setup).
 
-```
+{{ install_arguments.inc }}
-{{ cmd_help['install']['arguments'] }}
-```
 
 See [the installation documentation](Installing.md) for more info.
 
@@ -206,31 +182,23 @@ DESTDIR=/path/to/staging/area meson install -C builddir
 
 *(since 0.50.0)*
 
-```
+{{ rewrite_usage.inc }}
-{{ cmd_help['rewrite']['usage'] }}
-```
 
 Modifies the meson project.
 
-```
+{{ rewrite_arguments.inc }}
-{{ cmd_help['rewrite']['arguments'] }}
-```
 
 See [the meson file rewriter documentation](Rewriter.md) for more info.
 
 ### setup
 
-```
+{{ setup_usage.inc }}
-{{ cmd_help['setup']['usage'] }}
-```
 
 Configures a build directory for the meson project.
 
 This is the default meson command (invoked if there was no COMMAND supplied).
 
-```
+{{ setup_arguments.inc }}
-{{ cmd_help['setup']['arguments'] }}
-```
 
 See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
 
@@ -245,27 +213,19 @@ meson setup builddir
 
 *(since 0.49.0)*
 
-```
+{{ subprojects_usage.inc }}
-{{ cmd_help['subprojects']['usage'] }}
-```
 
 Manages subprojects of the meson project.
 
-```
+{{ subprojects_arguments.inc }}
-{{ cmd_help['subprojects']['arguments'] }}
-```
 
 ### test
 
-```
+{{ test_usage.inc }}
-{{ cmd_help['test']['usage'] }}
-```
 
 Run tests for the configure meson project.
 
-```
+{{ test_arguments.inc }}
-{{ cmd_help['test']['arguments'] }}
-```
 
 See [the unit test documentation](Unit-tests.md) for more info.
 
@@ -283,14 +243,10 @@ meson test -C builddir specific_test_1 specific_test_2
 
 ### wrap
 
-```
+{{ wrap_usage.inc }}
-{{ cmd_help['wrap']['usage'] }}
-```
 
 An utility to manage WrapDB dependencies.
 
-```
+{{ wrap_arguments.inc }}
-{{ cmd_help['wrap']['arguments'] }}
-```
 
 See [the WrapDB tool documentation](Using-wraptool.md) for more info.

docs/meson.build

@@ -2,22 +2,14 @@ project('Meson documentation', version: '1.0')
 
 cur_bdir = meson.current_build_dir()
 
-# Copy all files to build dir, since HotDoc uses relative paths
-run_command(
-    files('../tools/copy_files.py'),
-    '-C', meson.current_source_dir(),
-    '--output-dir', cur_bdir,
-    'markdown', 'theme', 'sitemap.txt', 
-    check: true)
-
 # Only the script knows which files are being generated
 docs_gen = custom_target(
     'gen_docs',
     input: files('markdown/index.md'),
-    output: 'gen_docs.dummy',
+    output: 'gen_docs.stamp',
     command: [
         files('../tools/regenerate_docs.py'),
-        '--output-dir', join_paths(cur_bdir, 'markdown'),
+        '--output-dir', cur_bdir,
         '--dummy-output-file', '@OUTPUT@',
     ],
     build_by_default: true,
@@ -26,15 +18,15 @@ docs_gen = custom_target(
 hotdoc = import('hotdoc')
 documentation = hotdoc.generate_doc(meson.project_name(),
     project_version: meson.project_version(),
-    sitemap: join_paths(cur_bdir, 'sitemap.txt'),
+    sitemap: 'sitemap.txt',
     build_by_default: true,
     depends: docs_gen,
-    index: join_paths(cur_bdir, 'markdown/index.md'),
+    index: 'markdown/index.md',
     install: false,
     extra_assets: ['images/'],
-    include_paths: [join_paths(cur_bdir, 'markdown')],
+    include_paths: ['markdown', cur_bdir],
     default_license: 'CC-BY-SAv4.0',
-    html_extra_theme: join_paths(cur_bdir, 'theme', 'extra'),
+    html_extra_theme: join_paths('theme', 'extra'),
     git_upload_repository: 'git@github.com:jpakkane/jpakkane.github.io.git',
     edit_on_github_repository: 'https://github.com/mesonbuild/meson',
     syntax_highlighting_activate: true,

run_unittests.py

@@ -4915,7 +4915,7 @@ class AllPlatformTests(BasePlatformTests):
         # The docs directory is not in release tarballs.
         if not os.path.isdir('docs'):
             raise unittest.SkipTest('Doc directory does not exist.')
-        doc_path = 'docs/markdown_dynamic/Commands.md'
+        doc_path = 'docs/markdown/Commands.md'
 
         md = None
         with open(doc_path, encoding='utf-8') as f:
@@ -4944,13 +4944,9 @@ class AllPlatformTests(BasePlatformTests):
 
         def get_data_pattern(command):
             return re.compile(
-                r'^```[\r\n]'
+                r'{{ ' + command + r'_usage.inc }}[\r\n]'
-                r'{{ cmd_help\[\'' + command + r'\'\]\[\'usage\'\] }}[\r\n]'
-                r'^```[\r\n]'
                 r'.*?'
-                r'^```[\r\n]'
+                r'{{ ' + command + r'_arguments.inc }}[\r\n]',
-                r'{{ cmd_help\[\'' + command + r'\'\]\[\'arguments\'\] }}[\r\n]'
-                r'^```',
                 flags = re.MULTILINE|re.DOTALL)
 
         for command in md_commands:

tools/regenerate_docs.py

@@ -20,7 +20,6 @@ Regenerate markdown docs by using `meson.py` from the root dir
 '''
 
 import argparse
-import jinja2
 import os
 import re
 import subprocess
@@ -108,20 +107,13 @@ def get_commands_data(root_dir: Path) -> T.Dict[str, T.Any]:
 
     return cmd_data
 
-def regenerate_commands(root_dir: Path, output_dir: Path) -> None:
+def generate_hotdoc_includes(root_dir: Path, output_dir: Path) -> None:
-    with open(root_dir/'docs'/'markdown_dynamic'/'Commands.md') as f:
-        template = f.read()
-
     cmd_data = get_commands_data(root_dir)
 
-    t = jinja2.Template(template, undefined=jinja2.StrictUndefined, keep_trailing_newline=True)
+    for cmd, parsed in cmd_data.items():
-    content = t.render(cmd_help=cmd_data)
+        for typ in parsed.keys():
-
+            with open(output_dir / (cmd+'_'+typ+'.inc'), 'w') as f:
-    output_file = output_dir/'Commands.md'
+                f.write(parsed[typ])
-    with open(output_file, 'w') as f:
-        f.write(content)
-
-    print(f'`{output_file}` was regenerated')
 
 def regenerate_docs(output_dir: PathLike,
                     dummy_output_file: T.Optional[PathLike]) -> None:
@@ -133,7 +125,7 @@ def regenerate_docs(output_dir: PathLike,
 
     root_dir = Path(__file__).resolve().parent.parent
 
-    regenerate_commands(root_dir, output_dir)
+    generate_hotdoc_includes(root_dir, output_dir)
 
     if dummy_output_file:
         with open(output_dir/dummy_output_file, 'w') as f: