doc: add documentation for pipewire-pulse modules

Add (minimal) reference documentation for each pipewire-pulse module.

Add some preprocessing to substitute @pulse_module_options@ in docs from
PW_KEY_MODULE_USAGE so the module options don't need to be repeated.

Produce Doxygen docs + generate manpages pipewire-pulse-modules.7,
pipewire-pulse-module-*.7

doc/dox/pulse-modules.dox

@@ -0,0 +1,52 @@
+/** \page page_pulse_modules Pulseaudio Modules
+
+PipeWire's Pulseaudio emulation implements several Pulseaudio modules.
+It only supports its own built-in modules, and cannot load external
+modules written for Pulseaudio.
+
+The built-in modules can be loaded using Pulseaudio client programs,
+for example `pactl load-module <module-name> <module-options>`. They
+can also added to `pipewire-pulse.conf`, typically by a drop-in file
+in `~/.config/pipewire/pipewire-pulse.conf.d/` containing the module
+name and its arguments
+```
+pulse.cmd = [
+    { cmd = "load-module" args = "module-null-sink sink_name=foo" flags = [ ] }
+]
+```
+
+List of known built-in modules:
+
+- \subpage page_pulse_module_alsa_sink
+- \subpage page_pulse_module_alsa_source
+- \subpage page_pulse_module_always_sink
+- \subpage page_pulse_module_combine_sink
+- \subpage page_pulse_module_echo_cancel
+- \subpage page_pulse_module_gsettings
+- \subpage page_pulse_module_jackdbus_detect
+- \subpage page_pulse_module_ladspa_sink
+- \subpage page_pulse_module_ladspa_source
+- \subpage page_pulse_module_loopback
+- \subpage page_pulse_module_native_protocol_tcp
+- \subpage page_pulse_module_null_sink
+- \subpage page_pulse_module_pipe_sink
+- \subpage page_pulse_module_pipe_source
+- \subpage page_pulse_module_raop_discover
+- \subpage page_pulse_module_remap_sink
+- \subpage page_pulse_module_remap_source
+- \subpage page_pulse_module_roc_sink
+- \subpage page_pulse_module_roc_sink_input
+- \subpage page_pulse_module_roc_source
+- \subpage page_pulse_module_rtp_recv
+- \subpage page_pulse_module_rtp_send
+- \subpage page_pulse_module_simple_protocol_tcp
+- \subpage page_pulse_module_switch_on_connect
+- \subpage page_pulse_module_tunnel_sink
+- \subpage page_pulse_module_tunnel_source
+- \subpage page_pulse_module_virtual_sink
+- \subpage page_pulse_module_virtual_source
+- \subpage page_pulse_module_x11_bell
+- \subpage page_pulse_module_zeroconf_discover
+- \subpage page_pulse_module_zeroconf_publish
+
+*/

doc/input-filter.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# -*- mode: python; coding: utf-8; eval: (blacken-mode); -*-
+r"""
+Doxygen input filter that:
+
+- adds \privatesection to all files
+- removes macros
+- parses pulse_module_options and substitutes it into @pulse_module_options@
+
+This is used for .c files, and causes Doxygen to not include
+any symbols from them, unless they also appeared in a header file.
+
+The Pulse module option parsing is used in documentation of Pulseaudio modules.
+"""
+import sys
+import re
+import os
+
+
+def main():
+    with open(sys.argv[1], "r") as f:
+        text = f.read()
+
+    text = re.sub("#define.*", "", text)
+
+    m = re.search(
+        r"static const char[* ]*const pulse_module_options\s+=\s+(.*?\")\s*;\s*$",
+        text,
+        re.M | re.S,
+    )
+    if m:
+        res = []
+        for line in m.group(1).splitlines():
+            m = re.match(r"\s*\"\s*([a-z0-9_]+)\s*=\s*(.*)\"\s*$", line)
+            if m:
+                name = m.group(1)
+                value = m.group(2).strip().strip("<>")
+                res.append(f"- `{name}`: {value}")
+
+        res = "\n * ".join(res)
+        text = text.replace("@pulse_module_options@", res)
+
+    print("/** \\privatesection */")
+    print(text)
+
+
+if __name__ == "__main__":
+    main()

doc/input-filter.sh

@@ -1,10 +0,0 @@
-#!/bin/bash
-#
-# Doxygen input filter that adds \privatesection to all files,
-# and removes macros.
-#
-# This is used for .c files, and causes Doxygen to not include
-# any symbols from them, unless they also appeared in a header file.
-#
-echo -n "/** \privatesection */ "
-sed -e 's/#define.*//' < "$1"

doc/meson.build

@@ -20,6 +20,7 @@ extra_docs = [
   'dox/index.dox',
   'dox/overview.dox',
   'dox/modules.dox',
+  'dox/pulse-modules.dox',
   'dox/internals/index.dox',
   'dox/internals/design.dox',
   'dox/internals/access.dox',
@@ -68,6 +69,9 @@ endforeach
 foreach h : module_sources
   inputs += meson.project_source_root() / 'src' / 'modules' / h
 endforeach
+foreach h : pipewire_module_protocol_pulse_sources
+  inputs += meson.project_source_root() / 'src' / 'modules' / h
+endforeach
 input_dirs = [ meson.project_source_root() / 'spa' / 'include' / 'spa' ]
 
 path_prefixes = [
@@ -141,7 +145,7 @@ pw_programs_dox = configure_file(input: 'programs.dox.in',
 input_dirs += [ 'doc/programs.dox' ]
 
 doxygen_layout = meson.project_source_root() / 'doc' / 'DoxygenLayout.xml'
-doxygen_filter_c = meson.project_source_root() / 'doc' / 'input-filter.sh'
+doxygen_filter_c = meson.project_source_root() / 'doc' / 'input-filter.py'
 doxygen_filter_h = meson.project_source_root() / 'doc' / 'input-filter-h.sh'
 
 doxyfile_conf.set('inputs', ' '.join(inputs + input_dirs))
@@ -177,9 +181,24 @@ if generate_module_manpages
      endif
    endforeach
 
+   module_manpage_names = []
    foreach m : module_sources
-       name = m.split('.c').get(0)
-       file = 'libpipewire-' + name + '.7'
+     name = m.split('.c').get(0)
+     file = f'libpipewire-@name@.7'
+     module_manpage_names += [[name, file]]
+   endforeach
+   foreach m : pipewire_module_protocol_pulse_sources
+     name = m.split('/').get(-1).split('.c').get(0)
+     if m.contains('/modules/') and name.startswith('module-')
+       name = f'pulse-@name@'
+       file = f'pipewire-@name@.7'
+       module_manpage_names += [[name, file]]
+     endif
+   endforeach
+
+   foreach item : module_manpage_names
+       name = item.get(0)
+       file = item.get(1)
 
        rst = custom_target(file + '.rst',
                 command : [python, module_man_rst_py, pandoc, name, '@INPUT@' ] + module_man_defines,

doc/module-man-rst.py

@@ -1,4 +1,5 @@
 #!/usr/bin/python3
+# -*- mode: python; coding: utf-8; eval: (blacken-mode); -*-
 """
 Convert Doxygen HTML documentation for a PipeWire module to RST.
 """
@@ -33,9 +34,7 @@ PipeWire is available from {PACKAGE_URL}
 SEE ALSO
 --------
 
-``pipewire(1)``,
-``pipewire.conf(5)``,
-``libpipewire-modules(7)``
+{seealso}
 """
 
 
@@ -68,11 +67,17 @@ def main():
         [args.pandoc, "-f", "html", "-t", "rst"], input=data, encoding="utf-8"
     )
 
-    if not content.strip():
-        content = "Undocumented."
+    if not content.strip() or content.lower().startswith("module name\n-----"):
+        content = "Undocumented.\n\n" + content
 
-    name = f"libpipewire-{args.module}"
-    subtitle = "PipeWire module"
+    if args.module.startswith("pulse-"):
+        name = re.sub(r"^pulse-module-", "module-", args.module)
+        seealso = "``pipewire-pulse(1)``, ``pipewire-pulse-modules(7)``"
+        subtitle = "PipeWire Pulseaudio module"
+    else:
+        name = f"libpipewire-{args.module}"
+        seealso = "``pipewire(1)``, ``pipewire.conf(5)``, ``libpipewire-modules(7)``"
+        subtitle = "PipeWire module"
 
     env = dict(
         content=content,
@@ -80,6 +85,7 @@ def main():
         name_underline="#" * len(name),
         subtitle=subtitle,
         subtitle_underline="-" * len(subtitle),
+        seealso=seealso,
     )
 
     for k, v in args.define:

doc/tree.dox

@@ -123,8 +123,9 @@ Support interfaces provided by host
 \}
 
 \page page_overview
-\page page_modules
 \page page_programs
+\page page_modules
+\page page_pulse_modules
 \page page_internals
 \page page_api
 \page page_tutorial