doc: link examples to Doxygen docs

Include examples to the documentation, using Doxygen's example system.

doc/Doxyfile.in

@@ -22,9 +22,9 @@ INPUT                  = @inputs@
 FILTER_PATTERNS        = "*.c=@c_input_filter@" "*.h=@h_input_filter@"
 FILE_PATTERNS          = "*.h" "*.c"
 RECURSIVE              = YES
-EXAMPLE_PATH           = "@top_srcdir@/src/tools" \
-                         "@top_srcdir@/src/examples"
-
+EXAMPLE_PATH           = "@top_srcdir@/src/examples" \
+                         "@top_srcdir@/spa/examples"
+EXAMPLE_PATTERNS       = "*.c"
 
 REFERENCED_BY_RELATION = NO
 REFERENCES_RELATION    = NO

doc/examples.dox.in

@@ -0,0 +1,9 @@
+/**
+
+\page page_examples List of example programs
+
+@example_ref@
+
+@example_doxygen@
+
+*/

doc/meson.build

@@ -84,6 +84,49 @@ cssfiles = [
   meson.source_root() / 'doc' / 'custom.css'
 ]
 
+# Example files (in order from simple to esoteric)
+example_files = [
+  'audio-src.c',
+  'audio-dsp-src.c',
+  'audio-dsp-filter.c',
+  'video-play.c',
+  'video-src.c',
+  'video-dsp-play.c',
+  'video-play-pull.c',
+  'video-play-reneg.c',
+  'video-src-alloc.c',
+  'video-src-reneg.c',
+  'export-sink.c',
+  'export-source.c',
+  'export-spa.c',
+  'export-spa-device.c',
+  'bluez-session.c',
+  'local-v4l2.c',
+  'spa/examples/adapter-control.c',
+  'spa/examples/example-control.c',
+  'spa/examples/local-libcamera.c',
+  'spa/examples/local-v4l2.c',
+]
+
+example_doxygen = []
+example_ref = []
+foreach h : example_files
+  example_doxygen += ['\\example ' + h,
+                      '\\snippet{doc} ' + h + ' title',
+                      '<br>',
+                      '\\snippet{doc} ' + h + ' doc']
+  example_ref += ['- \\ref ' + h + ' "": \snippet{doc} ' + h + ' title']
+endforeach
+
+examples_dox_conf = configuration_data()
+examples_dox_conf.set('example_doxygen', '\n'.join(example_doxygen))
+examples_dox_conf.set('example_ref', '\n'.join(example_ref))
+examples_dox = configure_file(input: 'examples.dox.in',
+                              output: 'examples.dox',
+                              configuration: examples_dox_conf)
+
+input_dirs += [ 'doc/examples.dox' ]
+
 doxyfile_conf.set('inputs', ' '.join(inputs + input_dirs))
 doxyfile_conf.set('cssfiles', ' '.join(cssfiles))
 doxyfile_conf.set('path_prefixes', ' '.join(path_prefixes))
@@ -100,7 +143,7 @@ if docdir == ''
 endif
 
 html_target = custom_target('pipewire-docs',
-                            input: [ doxyfile ] + inputs + cssfiles,
+                            input: [ doxyfile, examples_dox ] + inputs + cssfiles,
                             output: [ 'html' ],
                             command: [ doxygen, doxyfile ],
                             install: true,

doc/tutorial.dox

@@ -10,4 +10,11 @@ PipeWire API step-by-step with simple short examples.
 - \subpage page_tutorial5
 - \subpage page_tutorial6
 
+## More example programs
+
+- \ref audio-src.c "": \snippet{doc} audio-src.c title
+- \ref audio-dsp-filter.c "": \snippet{doc} audio-dsp-filter.c title
+- \ref video-play.c "": \snippet{doc} video-play.c title
+- \subpage page_examples
+
 */

spa/examples/adapter-control.c

@@ -22,6 +22,16 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Running audioadapter nodes.
+ [title]
+ [doc]
+ Runs an output audioadapter using audiotestsrc as follower
+ with an input audioadapter using alsa-pcm-sink as follower
+ for easy testing.
+ [doc]
+ */
 
 #include "config.h"
 

spa/examples/example-control.c

@@ -22,6 +22,11 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ [title]
+ */
+
 #include "config.h"
 
 #include <math.h>

spa/examples/local-libcamera.c

@@ -25,6 +25,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Example using libspa-libcamera, with only \ref api_spa
+ [title]
+ */
+
 #include "config.h"
 
 #include <string.h>

spa/examples/local-v4l2.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Example using libspa-v4l2, with only \ref api_spa
+ [title]
+ */
+
 #include "config.h"
 
 #include <string.h>

src/examples/audio-dsp-filter.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Audio filter using \ref pw_filter "pw_filter".
+ [title]
+ */
+
 #include <stdio.h>
 #include <errno.h>
 #include <math.h>

src/examples/audio-dsp-src.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Audio source using \ref pw_filter "pw_filter"
+ [title]
+ */
+
 #include <stdio.h>
 #include <errno.h>
 #include <math.h>

src/examples/audio-src.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Audio source using \ref pw_stream "pw_stream".
+ [title]
+ */
+
 #include <stdio.h>
 #include <errno.h>
 #include <math.h>

src/examples/bluez-session.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Using the \ref spa_device "SPA Device API", among other things.
+ [title]
+ */
+
 #include <string.h>
 #include <stdio.h>
 #include <errno.h>

src/examples/export-sink.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Exporting and implementing a video sink SPA node, using \ref api_pw_core.
+ [title]
+ */
+
 #include <errno.h>
 #include <stdio.h>
 #include <sys/mman.h>

src/examples/export-source.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Exporting and implementing a video source SPA node, using \ref api_pw_core.
+ [title]
+ */
+
 #include <errno.h>
 #include <stdio.h>
 #include <math.h>

src/examples/export-spa-device.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Exporting and loading a SPA device, using \ref api_pw_core.
+ [title]
+ */
+
 #include <stdio.h>
 #include <sys/mman.h>
 #include <signal.h>

src/examples/export-spa.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Exporting and loading a SPA node, using \ref api_pw_core.
+ [title]
+ */
+
 #include <stdio.h>
 #include <sys/mman.h>
 #include <signal.h>

src/examples/local-v4l2.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Using libspa-v4l2
+ [title]
+ */
+
 #include <stdio.h>
 #include <sys/mman.h>
 

src/examples/sdl.h

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ SDL2 video format conversions
+ [title]
+ */
+
 #include <SDL2/SDL.h>
 
 #include <spa/utils/type.h>

src/examples/video-dsp-play.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Video input stream using \ref pw_filter "pw_filter".
+ [title]
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <sys/mman.h>

src/examples/video-play-pull.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Video input stream using \ref pw_stream_trigger_process, for pull mode.
+ [title]
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <signal.h>

src/examples/video-play-reneg.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Video input stream using \ref pw_stream "pw_stream", with format renegotiation.
+ [title]
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <signal.h>

src/examples/video-play.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Video input stream using \ref pw_stream "pw_stream".
+ [title]
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <signal.h>

src/examples/video-src-alloc.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Allocating buffer memory and sending fds to the server.
+ [title]
+ */
+
 #include "config.h"
 
 #include <stdio.h>

src/examples/video-src-reneg.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Renegotiating video producer and consumer formats with \ref pw_stream
+ [title]
+ */
+
 #include "config.h"
 
 #include <stdio.h>

src/examples/video-src.c

@@ -22,6 +22,12 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/*
+ [title]
+ Video source using \ref pw_stream.
+ [title]
+ */
+
 #include <stdio.h>
 #include <errno.h>
 #include <signal.h>