From 98a0e54d5fcf9251e993a0b5e107c9958ac5b0a2 Mon Sep 17 00:00:00 2001 From: Pauli Virtanen Date: Sat, 9 Oct 2021 23:25:29 +0300 Subject: [PATCH] doc: link examples to Doxygen docs Include examples to the documentation, using Doxygen's example system. --- doc/Doxyfile.in | 6 ++--- doc/examples.dox.in | 9 +++++++ doc/meson.build | 45 +++++++++++++++++++++++++++++++- doc/tutorial.dox | 7 +++++ spa/examples/adapter-control.c | 10 +++++++ spa/examples/example-control.c | 5 ++++ spa/examples/local-libcamera.c | 6 +++++ spa/examples/local-v4l2.c | 6 +++++ src/examples/audio-dsp-filter.c | 6 +++++ src/examples/audio-dsp-src.c | 6 +++++ src/examples/audio-src.c | 6 +++++ src/examples/bluez-session.c | 6 +++++ src/examples/export-sink.c | 6 +++++ src/examples/export-source.c | 6 +++++ src/examples/export-spa-device.c | 6 +++++ src/examples/export-spa.c | 6 +++++ src/examples/local-v4l2.c | 6 +++++ src/examples/sdl.h | 6 +++++ src/examples/video-dsp-play.c | 6 +++++ src/examples/video-play-pull.c | 6 +++++ src/examples/video-play-reneg.c | 6 +++++ src/examples/video-play.c | 6 +++++ src/examples/video-src-alloc.c | 6 +++++ src/examples/video-src-reneg.c | 6 +++++ src/examples/video-src.c | 6 +++++ 25 files changed, 192 insertions(+), 4 deletions(-) create mode 100644 doc/examples.dox.in diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 6c7118d0d..82ec2edb6 100644 --- a/doc/Doxyfile.in +++ b/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 diff --git a/doc/examples.dox.in b/doc/examples.dox.in new file mode 100644 index 000000000..fd11ac890 --- /dev/null +++ b/doc/examples.dox.in @@ -0,0 +1,9 @@ +/** + +\page page_examples List of example programs + +@example_ref@ + +@example_doxygen@ + +*/ diff --git a/doc/meson.build b/doc/meson.build index 9857e7dec..b4ae72f76 100644 --- a/doc/meson.build +++ b/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', + '
', + '\\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, diff --git a/doc/tutorial.dox b/doc/tutorial.dox index 275cb5194..e9c70fc6f 100644 --- a/doc/tutorial.dox +++ b/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 + */ diff --git a/spa/examples/adapter-control.c b/spa/examples/adapter-control.c index af6f41f86..39a22a4e2 100644 --- a/spa/examples/adapter-control.c +++ b/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" diff --git a/spa/examples/example-control.c b/spa/examples/example-control.c index 3eedc8710..f26960cd8 100644 --- a/spa/examples/example-control.c +++ b/spa/examples/example-control.c @@ -22,6 +22,11 @@ * DEALINGS IN THE SOFTWARE. */ +/* + [title] + [title] + */ + #include "config.h" #include diff --git a/spa/examples/local-libcamera.c b/spa/examples/local-libcamera.c index 17fed5981..88ad02bfc 100644 --- a/spa/examples/local-libcamera.c +++ b/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 diff --git a/spa/examples/local-v4l2.c b/spa/examples/local-v4l2.c index 6968d3af7..bd6de7b6d 100644 --- a/spa/examples/local-v4l2.c +++ b/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 diff --git a/src/examples/audio-dsp-filter.c b/src/examples/audio-dsp-filter.c index e6eee1349..9f1992b48 100644 --- a/src/examples/audio-dsp-filter.c +++ b/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 #include #include diff --git a/src/examples/audio-dsp-src.c b/src/examples/audio-dsp-src.c index cbef3c778..beaecfe72 100644 --- a/src/examples/audio-dsp-src.c +++ b/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 #include #include diff --git a/src/examples/audio-src.c b/src/examples/audio-src.c index f112307ec..561672d71 100644 --- a/src/examples/audio-src.c +++ b/src/examples/audio-src.c @@ -22,6 +22,12 @@ * DEALINGS IN THE SOFTWARE. */ +/* + [title] + Audio source using \ref pw_stream "pw_stream". + [title] + */ + #include #include #include diff --git a/src/examples/bluez-session.c b/src/examples/bluez-session.c index 08d2b9e1d..d46b5d9a0 100644 --- a/src/examples/bluez-session.c +++ b/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 #include #include diff --git a/src/examples/export-sink.c b/src/examples/export-sink.c index e9b6c8474..43234b649 100644 --- a/src/examples/export-sink.c +++ b/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 #include #include diff --git a/src/examples/export-source.c b/src/examples/export-source.c index 8a85b9410..974c6dea5 100644 --- a/src/examples/export-source.c +++ b/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 #include #include diff --git a/src/examples/export-spa-device.c b/src/examples/export-spa-device.c index 30409ecca..4629a0275 100644 --- a/src/examples/export-spa-device.c +++ b/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 #include #include diff --git a/src/examples/export-spa.c b/src/examples/export-spa.c index 39f2b571a..ba2f29990 100644 --- a/src/examples/export-spa.c +++ b/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 #include #include diff --git a/src/examples/local-v4l2.c b/src/examples/local-v4l2.c index cd9c08844..035491d85 100644 --- a/src/examples/local-v4l2.c +++ b/src/examples/local-v4l2.c @@ -22,6 +22,12 @@ * DEALINGS IN THE SOFTWARE. */ +/* + [title] + Using libspa-v4l2 + [title] + */ + #include #include diff --git a/src/examples/sdl.h b/src/examples/sdl.h index b3db3073a..cb7b87a6f 100644 --- a/src/examples/sdl.h +++ b/src/examples/sdl.h @@ -22,6 +22,12 @@ * DEALINGS IN THE SOFTWARE. */ +/* + [title] + SDL2 video format conversions + [title] + */ + #include #include diff --git a/src/examples/video-dsp-play.c b/src/examples/video-dsp-play.c index 566b10243..05828b591 100644 --- a/src/examples/video-dsp-play.c +++ b/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 #include #include diff --git a/src/examples/video-play-pull.c b/src/examples/video-play-pull.c index b831b15e8..27694fdf3 100644 --- a/src/examples/video-play-pull.c +++ b/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 #include #include diff --git a/src/examples/video-play-reneg.c b/src/examples/video-play-reneg.c index ee204775a..4b4d6bb39 100644 --- a/src/examples/video-play-reneg.c +++ b/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 #include #include diff --git a/src/examples/video-play.c b/src/examples/video-play.c index 660f44dc1..e19caf717 100644 --- a/src/examples/video-play.c +++ b/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 #include #include diff --git a/src/examples/video-src-alloc.c b/src/examples/video-src-alloc.c index 166828e1e..92d6473dc 100644 --- a/src/examples/video-src-alloc.c +++ b/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 diff --git a/src/examples/video-src-reneg.c b/src/examples/video-src-reneg.c index eda664de2..11b4c1420 100644 --- a/src/examples/video-src-reneg.c +++ b/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 diff --git a/src/examples/video-src.c b/src/examples/video-src.c index 403dc66f5..7457ade84 100644 --- a/src/examples/video-src.c +++ b/src/examples/video-src.c @@ -22,6 +22,12 @@ * DEALINGS IN THE SOFTWARE. */ +/* + [title] + Video source using \ref pw_stream. + [title] + */ + #include #include #include