docs: start using custom_target instead of run_command for sitemap

Intead of passing around the output of the config generator program,
which consists of paths joined by a separator we can have the generator
simply produce an extra file containing those paths.

This commit only implements the new approach for the core plugins, as
this was needed to avoid spurious meson rebuilds when the pre-commit
hook regenerates the core plugins_cache.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/8231>

ci/scripts/build-docs.sh

@@ -26,7 +26,9 @@ git checkout $(git ls-files 'subprojects/*.wrap')
 git checkout $(git ls-files 'subprojects/*.wrap')
 ./ci/scripts/check-diff.py
 
-export GI_TYPELIB_PATH="$PWD/girs"
-hotdoc run --conf-file "$builddir/subprojects/gst-docs/GStreamer-doc.json"
+ninja -C "$builddir" subprojects/gst-docs/sitemap.txt
+
+export GI_TYPELIB_PATH=$PWD/girs
+hotdoc run --conf-file build/subprojects/gst-docs/GStreamer-doc.json
 
 mv "$builddir/subprojects/gst-docs/GStreamer-doc/html" documentation/

subprojects/gst-docs/meson.build

@@ -61,6 +61,7 @@ libs = ''
 plugins_doc = ''
 deps = []
 plugins_sitemap = ''
+plugin_configs = []
 if built_subprojects != ''
     foreach project_name: built_subprojects.split(',')
         sub = subproject(project_name)
@@ -83,6 +84,8 @@ if built_subprojects != ''
             foreach plugin_doc: sub.get_variable('gst_plugins_doc', [])
               plugins_doc += plugin_doc + pathsep
             endforeach
+
+            plugin_configs += sub.get_variable('plugin_hotdoc_configs', [])
         else
             message('@0@ did not build hotdoc documentation, can\'t build API doc'.format(project_name))
         endif
@@ -96,10 +99,17 @@ else
   index = 'markdown/simple-index.md'
 endif
 sitemap_gen = find_program('scripts/generate_sitemap.py')
-sitemap = configure_file(command: [sitemap_gen, '@INPUT@', '@OUTPUT@',
-  'gi-index', libs, plugins_doc],
+sitemap = custom_target(command: [
+  sitemap_gen,
+  '--input-sitemap', '@INPUT@',
+  '--output-sitemap', '@OUTPUT@',
+  '--markdown-index', 'gi-index',
+  '--libs', libs,
+  '--plugins', plugins_doc,
+  '--plugin-configs', plugin_configs],
   input: 'sitemap.txt',
   output: 'sitemap.txt')
+deps += [sitemap]
 
 html_theme = 'https://github.com/hotdoc/hotdoc_lumen_theme/releases/download/0.16/hotdoc_lumen_theme-0.16.tar.xz?sha256=b7d7dde51285d1c90836c44ae298754e4cfa957e9a6d14ee5844b8a2cac04b5a'
 

subprojects/gst-docs/scripts/generate_sitemap.py

@@ -1,18 +1,39 @@
 #!/usr/bin/env python3
 import os
 import sys
-
+from argparse import ArgumentParser
+from pathlib import Path as P
+import json
 
 if __name__ == "__main__":
-    in_, out, index_md = sys.argv[1], sys.argv[2], sys.argv[3]
+    parser = ArgumentParser()
+    parser.add_argument('--input-sitemap', type=P)
+    parser.add_argument('--output-sitemap', type=P)
+    parser.add_argument('--markdown-index', type=P)
+    parser.add_argument('--libs', type=str)
+    parser.add_argument('--plugins', type=str)
+    parser.add_argument('--plugin-configs', nargs='*', default=[])
+
+    args = parser.parse_args()
+
+    in_ = args.input_sitemap
+    out = args.output_sitemap
+    index_md = args.markdown_index
+    libs = args.libs
+    plugins = args.plugins
+    plugin_configs = args.plugin_configs
+
     with open(in_) as f:
-
         index = f.read()
-        index = '\n'.join(l for l in index.splitlines())
+        index = '\n'.join(line for line in index.splitlines())
 
-        if sys.argv[4]:
-            libs, plugins = sys.argv[4].split(os.pathsep), sorted(
-                sys.argv[5].replace('\n', '').split(os.pathsep), key=lambda x: os.path.basename(x))
+        if libs:
+            libs = libs.split(os.pathsep)
+            plugins = plugins.replace('\n', '').split(os.pathsep)
+            for config in plugin_configs:
+                with open(config) as f:
+                    plugins += json.load(f)
+            plugins = sorted(plugins, key=lambda x: os.path.basename(x))
             index += '\n\tlibs.md'
             for lib in libs:
                 if not lib:

subprojects/gstreamer/docs/gst-plugins-doc-cache-generator.py

@@ -48,6 +48,7 @@ class GstPluginsHotdocConfGen:
         parser.add_argument('--include_paths', nargs='*', default=[])
         parser.add_argument('--gst_c_source_filters', nargs='*', default=[])
         parser.add_argument('--gst_c_source_file', type=P)
+        parser.add_argument('--output', type=P)
 
         parser.parse_args(namespace=self, args=sys.argv[2:])
 
@@ -92,6 +93,10 @@ class GstPluginsHotdocConfGen:
                         'gst_order_generated_subpages': True,
                     }, f, indent=4)
 
+        if self.output is not None:
+            with self.output.open('w') as f:
+                json.dump(plugin_files, f, indent=4)
+
         return plugin_files
 
 

subprojects/gstreamer/docs/meson.build

@@ -168,7 +168,9 @@ cdir = meson.current_source_dir()
 
 doc_source_file = configure_file(output: 'doc_sources.json', configuration: plugin_sources, output_format: 'json')
 
-gst_plugins_doc = run_command(
+plugin_hotdoc_configs = custom_target(
+  'build-hotdoc-configs',
+  command: [
     plugins_cache_generator,
     'hotdoc-config',
     '--builddir', meson.current_build_dir(),
@@ -178,8 +180,12 @@ gst_plugins_doc = run_command(
     '--gst_index', cdir / 'plugins/index.md',
     '--gst_c_source_file', doc_source_file,
     '--gst_c_sources',
-        cdir / '../plugins/*/*.c',
-        cdir / '../plugins/*/*.h',
-    '--gst_cache_file', plugins_cache,
-    check: true,
-).stdout().split(pathsep)
+      cdir / '../plugins/*/*.c',
+      cdir / '../plugins/*/*.h',
+    '--gst_cache_file', '@INPUT@',
+    '--output', '@OUTPUT@',
+  ],
+  input: plugins_cache,
+  output: 'hotdoc-configs.json',
+  depends: [hotdoc_plugin_scanner],
+)