docs: start listing sources explicitly in hotdoc configuration files

A JSON configuration file is generated for core plugins, which maps
plugin names with sources to parse for docstrings.

The file is then opened by the configuration generator script, which
will now favor explicitly listed files to (usually wildcarded) paths
passed on its command line.

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

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

@@ -47,17 +47,32 @@ class GstPluginsHotdocConfGen:
         parser.add_argument('--project_version')
         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.parse_args(namespace=self, args=sys.argv[2:])
 
     def generate_plugins_configs(self):
         plugin_files = []
+
+        if self.gst_c_source_file is not None:
+            with self.gst_c_source_file.open() as fd:
+                gst_c_source_map = json.load(fd)
+        else:
+            gst_c_source_map = {}
+
         with self.gst_cache_file.open() as fd:
             all_plugins = json.load(fd)
 
             for plugin_name in all_plugins.keys():
                 conf = self.builddir / f'plugin-{plugin_name}.json'
                 plugin_files.append(str(conf))
+
+                # New-style, sources are explicitly provided, as opposed to using wildcards
+                if plugin_name in gst_c_source_map:
+                    gst_c_sources = gst_c_source_map[plugin_name].split(os.pathsep)
+                else:
+                    gst_c_sources = self.gst_c_sources
+
                 with conf.open('w') as f:
                     json.dump({
                         'sitemap': str(self.sitemap),
@@ -71,7 +86,7 @@ class GstPluginsHotdocConfGen:
                         'gst_plugin_name': plugin_name,
                         'c_flags': self.c_flags,
                         'gst_smart_index': True,
-                        'gst_c_sources': self.gst_c_sources,
+                        'gst_c_sources': gst_c_sources,
                         'gst_c_source_filters': [str(s) for s in self.gst_c_source_filters],
                         'include_paths': self.include_paths,
                         'gst_order_generated_subpages': True,

subprojects/gstreamer/docs/meson.build

@@ -165,11 +165,9 @@ foreach lib: libs
 endforeach
 
 cdir = meson.current_source_dir()
-if host_machine.system() == 'windows'
-  pathsep = ';'
-else
-  pathsep = ':'
-endif
+
+doc_source_file = configure_file(output: 'doc_sources.json', configuration: plugin_sources, output_format: 'json')
+
 gst_plugins_doc = run_command(
     plugins_cache_generator,
     'hotdoc-config',
@@ -178,6 +176,7 @@ gst_plugins_doc = run_command(
     '--sitemap', cdir / 'plugins/sitemap.txt',
     '--index', cdir / 'plugins/index.md',
     '--gst_index', cdir / 'plugins/index.md',
+    '--gst_c_source_file', doc_source_file,
     '--gst_c_sources',
         cdir / '../plugins/*/*.c',
         cdir / '../plugins/*/*.h',

subprojects/gstreamer/meson.build

@@ -678,6 +678,11 @@ if host_system == 'darwin'
   pkgconfig_libs = ['-Wl,-rpath,${libdir}']
 endif
 
+if host_machine.system() == 'windows'
+  pathsep = ';'
+else
+  pathsep = ':'
+endif
 
 gst_libraries = []
 subdir('cmake')

subprojects/gstreamer/plugins/elements/meson.build

@@ -26,6 +26,34 @@ gst_elements_sources = [
   'gstvalve.c',
 ]
 
+gst_elements_headers = [
+  'gstcapsfilter.h',
+  'gstclocksync.h',
+  'gstconcat.h',
+  'gstcoreelementselements.h',
+  'gstdataurisrc.h',
+  'gstdownloadbuffer.h',
+  'gstelements_private.h',
+  'gstfakesink.h',
+  'gstfakesrc.h',
+  'gstfdsink.h',
+  'gstfdsrc.h',
+  'gstfilesink.h',
+  'gstfilesrc.h',
+  'gstfunnel.h',
+  'gstidentity.h',
+  'gstinputselector.h',
+  'gstmultiqueue.h',
+  'gstoutputselector.h',
+  'gstqueue2.h',
+  'gstqueue.h',
+  'gstsparsefile.h',
+  'gststreamiddemux.h',
+  'gsttee.h',
+  'gsttypefindelement.h',
+  'gstvalve.h',
+]
+
 gst_elements = library('gstcoreelements',
   gst_elements_sources,
   c_args : gst_c_args,
@@ -36,3 +64,12 @@ gst_elements = library('gstcoreelements',
 )
 
 plugins += [gst_elements]
+
+doc_sources = []
+foreach s: gst_elements_sources + gst_elements_headers
+  doc_sources += meson.current_source_dir() / s
+endforeach
+
+plugin_sources += {
+  'coreelements': pathsep.join(doc_sources)
+}

subprojects/gstreamer/plugins/meson.build

@@ -1,4 +1,5 @@
 plugins = []
+plugin_sources = {}
 subdir('elements')
 if not get_option('coretracers').disabled()
   subdir('tracers')

subprojects/gstreamer/plugins/tracers/meson.build

@@ -13,6 +13,15 @@ gst_tracers_sources = [
   'gstfactories.c'
 ]
 
+gst_tracers_headers = [
+  'gstfactories.h',
+  'gstlatency.h',
+  'gstleaks.h',
+  'gstlog.h',
+  'gstrusage.h',
+  'gststats.h',
+]
+
 if gst_debug
   gst_tracers_sources += ['gstlog.c']
 endif
@@ -32,3 +41,12 @@ gst_tracers = library('gstcoretracers',
   install_dir : plugins_install_dir,
 )
 plugins += [gst_tracers]
+
+doc_sources = []
+foreach s: gst_tracers_sources + gst_tracers_headers
+  doc_sources += meson.current_source_dir() / s
+endforeach
+
+plugin_sources += {
+  'coretracers': pathsep.join(doc_sources)
+}