Repository: mesonbuild/meson

Issue:
hotdoc module generates broken "Edit on github" links
- Browse to https://mesonbuild.com/Hotdoc-module.html
- Click "Edit on github"
- Be redirected to https://github.com/mesonbuild/meson//edit/master/docs/builddir/markdown/Hotdoc-module.md
- notice "builddir/" in the url

/cc @thiblahute 


Discussion:
Ah, that broke recently, I guess in hotdoc? @MathieuDuponchelle any guess?
checking
This is caused by https://github.com/mesonbuild/meson/commit/b6981bd16eb0227173a85d4b26a4b060dab16998 , I'm afraid this isn't something that can be fixed directly in hotdoc. The assumption made by the edit-on-github plugin is that the source file for a page is version-controlled, that commit broke this assumption. I think the whole mechanism implemented in this commit is pretty misguided, and we could have looked for a better solution together, but things being as they are the only solution would be for the extension to accept a new page meta, that meta would specify the actual path (from the root of the repo) of the version-controlled source file.

Something like:

```
original-source: docs/markdown/foo.md
```

in the yaml front matter (naming is hard sorry). The python script used to regenerate the sources would then have the responsibility of injecting that information in the front matter, taking care of doing so correctly, ie ideally not parsing with regexes too much :D
> I think the whole mechanism implemented in this commit is pretty misguided, and we could have looked for a better solution together, but things being as they are

Hmm, if there is a better solution maybe we could switch to that? What are you thinking of?
hotdoc supports sthg called transclusion: https://hotdoc.github.io/syntax-extensions.html#smart-file-inclusion-syntax . Interestingly it looks like the mechanism @TheQwertiest implemented uses the same syntax for that, presumably unknowingly, I assume this is jinja syntax.

In any case, you could switch to sthg like:

{{ cmd_help_configure_arguments.md }}

generate one markdown file per subcommand, with contents looking like:

    ```
    configure help goes here
    ```

And add an include path for hotdoc to look into

I haven't looked in details though, but I reckon this could work and not require copying everything to the build dir

Resolving patch:
diff --git a/run_unittests.py b/run_unittests.py
--- a/run_unittests.py
+++ b/run_unittests.py
@@ -4915,7 +4915,7 @@ def test_commands_documented(self):
         # 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 @@ def test_commands_documented(self):
 
         def get_data_pattern(command):
             return re.compile(
-                r'^```[\r\n]'
-                r'{{ cmd_help\[\'' + command + r'\'\]\[\'usage\'\] }}[\r\n]'
-                r'^```[\r\n]'
+                r'{{ ' + command + r'_usage.inc }}[\r\n]'
                 r'.*?'
-                r'^```[\r\n]'
-                r'{{ cmd_help\[\'' + command + r'\'\]\[\'arguments\'\] }}[\r\n]'
-                r'^```',
+                r'{{ ' + command + r'_arguments.inc }}[\r\n]',
                 flags = re.MULTILINE|re.DOTALL)
 
         for command in md_commands:
@@ -7533,7 +7529,7 @@ def test_pkg_config_option(self):
             '-Dbuild.pkg_config_path=' + os.path.join(testdir, 'build_extra_path'),
             '-Dpkg_config_path=' + os.path.join(testdir, 'host_extra_path'),
         ])
-    
+
     def test_run_native_test(self):
         '''
         https://github.com/mesonbuild/meson/issues/7997
diff --git a/tools/regenerate_docs.py b/tools/regenerate_docs.py
--- a/tools/regenerate_docs.py
+++ b/tools/regenerate_docs.py
@@ -20,7 +20,6 @@
 '''
 
 import argparse
-import jinja2
 import os
 import re
 import subprocess
@@ -108,20 +107,13 @@ def clean_dir_arguments(text: str) -> str:
 
     return cmd_data
 
-def regenerate_commands(root_dir: Path, output_dir: Path) -> None:
-    with open(root_dir/'docs'/'markdown_dynamic'/'Commands.md') as f:
-        template = f.read()
-
+def generate_hotdoc_includes(root_dir: Path, output_dir: Path) -> None:
     cmd_data = get_commands_data(root_dir)
 
-    t = jinja2.Template(template, undefined=jinja2.StrictUndefined, keep_trailing_newline=True)
-    content = t.render(cmd_help=cmd_data)
-
-    output_file = output_dir/'Commands.md'
-    with open(output_file, 'w') as f:
-        f.write(content)
-
-    print(f'`{output_file}` was regenerated')
+    for cmd, parsed in cmd_data.items():
+        for typ in parsed.keys():
+            with open(output_dir / (cmd+'_'+typ+'.inc'), 'w') as f:
+                f.write(parsed[typ])
 
 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:


Test patch: