From ac05f6bb03d4698e117c4132e4c615129fd65730 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Fri, 7 May 2021 09:09:45 +1000 Subject: [PATCH] doc: add the various markdown prose docs to the doxygen output Note that the order of the includes matters - that's how doxygen will sort them. There is no specific structure other than the include order - one reason why the headers are being changed. Without polluting the markdown files with doxygen commands we cannot use \subpage, so all files convert to a regular \page and are listed as flat hierarchy in the sidebar (and in Related Pages). Changing the headers at least provides some visual grouping with comon prefixes. --- doc/architecture.md | 6 +++--- doc/meson.build | 23 +++++++++++++++++++++++ doc/objects_design.md | 2 +- doc/pulseaudio.md | 2 +- doc/spa/buffer.md | 2 ++ doc/spa/index.md | 5 +++++ doc/spa/pod.md | 2 +- doc/tutorial-index.md | 2 +- doc/tutorial1.md | 4 ++-- doc/tutorial2.md | 5 +++-- doc/tutorial3.md | 4 ++-- doc/tutorial4.md | 4 ++-- doc/tutorial5.md | 4 ++-- doc/tutorial6.md | 4 ++-- 14 files changed, 50 insertions(+), 19 deletions(-) diff --git a/doc/architecture.md b/doc/architecture.md index c8d6d5795..1d6d99f69 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -1,9 +1,9 @@ -# Architecture +# PipeWire Architecture There are 2 main components that make up the PipeWire library: - 1) An implementation of a graph based media processing engine. - 2) An asynchronous IPC mechanism to manipulate and introspect +1. An implementation of a graph based media processing engine. +2. An asynchronous IPC mechanism to manipulate and introspect a graph in another process. There is usually a daemon that implements the global graph and diff --git a/doc/meson.build b/doc/meson.build index 2b100b3ca..e61f63563 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -18,6 +18,29 @@ foreach h : pipewire_sources inputs += meson.source_root() / 'src' / 'pipewire' / h endforeach +extra_docs = [ + 'overview.md', + 'design.txt', + 'architecture.md', + 'objects_design.md', + 'tutorial-index.md', + 'tutorial1.md', + 'tutorial2.md', + 'tutorial3.md', + 'tutorial4.md', + 'tutorial5.md', + 'tutorial6.md', + 'spa/index.md', + 'spa/design.md', + 'spa/pod.md', + 'spa/buffer.md', + 'pulseaudio.md', +] + +foreach extra : extra_docs + inputs += meson.source_root() / 'doc' / extra +endforeach + doxyfile_conf.set('inputs', ' '.join(inputs)) doxyfile = configure_file(input: 'Doxyfile.in', diff --git a/doc/objects_design.md b/doc/objects_design.md index 641092961..617114bb8 100644 --- a/doc/objects_design.md +++ b/doc/objects_design.md @@ -1,4 +1,4 @@ -# Objects Design +# PipeWire Objects Design This document is a design reference on the various objects that exist in the PipeWire media and session management graphs, explaining what these diff --git a/doc/pulseaudio.md b/doc/pulseaudio.md index 51f49260c..51dc03f6e 100644 --- a/doc/pulseaudio.md +++ b/doc/pulseaudio.md @@ -1,4 +1,4 @@ -# ALSA +# Internals - Mapping between ALSA and streams This explains the mapping between alsa cards and streams and session manager objects. diff --git a/doc/spa/buffer.md b/doc/spa/buffer.md index eee9110e5..9a9a791f6 100644 --- a/doc/spa/buffer.md +++ b/doc/spa/buffer.md @@ -1,3 +1,5 @@ +# SPA Buffers + > What is the array of `spa_data` in `spa_buffer`? A buffer contains metadata and data. There can be many metadata items (headers, color info, cursor position, etc) in the buffer. The metadata items are stored in the metas array. In the same way, the buffer can contain multiple data blocks in the datas array. Each data block is, for example, a video plane or an audio channel. There are `n_datas` of those blocks. diff --git a/doc/spa/index.md b/doc/spa/index.md index 12a03d0ab..f60667684 100644 --- a/doc/spa/index.md +++ b/doc/spa/index.md @@ -1,4 +1,9 @@ # SPA (Simple Plugin API) +SPA (Simple Plugin API) is an extensible API to implement all kinds of +plugins. It is inspired by many other plugin APIs, mostly LV2 and +GStreamer. + * SPA [Design](design.md) * [Data format](pod.md) +* SPA [Buffers](buffer.md) diff --git a/doc/spa/pod.md b/doc/spa/pod.md index 597148f7b..6231fc90e 100644 --- a/doc/spa/pod.md +++ b/doc/spa/pod.md @@ -1,4 +1,4 @@ -# POD +# SPA POD POD (plain old data) is a sort of data container. It is comparable to DBus Variant or LV2 Atom. diff --git a/doc/tutorial-index.md b/doc/tutorial-index.md index afec7ccba..ed76f3616 100644 --- a/doc/tutorial-index.md +++ b/doc/tutorial-index.md @@ -1,4 +1,4 @@ -# PipeWire Tutorial +# Tutorial - The PipeWire API Welcome to the PipeWire tutorial. The goal is to learn PipeWire API step-by-step with simple short examples. diff --git a/doc/tutorial1.md b/doc/tutorial1.md index d913ebbbc..6dbdc08de 100644 --- a/doc/tutorial1.md +++ b/doc/tutorial1.md @@ -1,6 +1,6 @@ -[[index]](tutorial-index.md) [[next]](tutorial2.md) +# Tutorial - Part 1: Getting started -# Getting started (Tutorial 1) +[[index]](tutorial-index.md) [[next]](tutorial2.md) In this tutorial we show the basics of a simple PipeWire application. Use this tutorial to get started and help you set up your development diff --git a/doc/tutorial2.md b/doc/tutorial2.md index 73a6ece38..1f0fbfbf7 100644 --- a/doc/tutorial2.md +++ b/doc/tutorial2.md @@ -1,8 +1,9 @@ +# Tutorial - Part 2: Enumerating objects + [[previous]](tutorial1.md) [[index]](tutorial-index.md) [[next]](tutorial3.md) -# Enumerating objects (Tutorial 2) -In this tutorial we show how to connect to a PipeWire daemon and +In this tutorial we show how to connect to a PipeWire daemon and enumerate the objects that it has. Let take a look at the following application to start. diff --git a/doc/tutorial3.md b/doc/tutorial3.md index 279bc9b67..6a46b4676 100644 --- a/doc/tutorial3.md +++ b/doc/tutorial3.md @@ -1,6 +1,6 @@ -[[previous]](tutorial2.md) [[index]](tutorial-index.md) [[next]](tutorial4.md) +# Tutorial - Part 3: Forcing a roundtrip (Tutorial 3) -# Forcing a roundtrip (Tutorial 3) +[[previous]](tutorial2.md) [[index]](tutorial-index.md) [[next]](tutorial4.md) In this tutorial we show how to force a roundtrip to the server to make sure an action completed. diff --git a/doc/tutorial4.md b/doc/tutorial4.md index eb08a17ec..4ba6d1b9c 100644 --- a/doc/tutorial4.md +++ b/doc/tutorial4.md @@ -1,6 +1,6 @@ -[[previous]](tutorial3.md) [[index]](tutorial-index.md) [[next]](tutorial5.md) +# Tutorial - Part 4: Playing a tone -# Playing a tone (Tutorial 4) +[[previous]](tutorial3.md) [[index]](tutorial-index.md) [[next]](tutorial5.md) In this tutorial we show how to use a stream to play a tone. diff --git a/doc/tutorial5.md b/doc/tutorial5.md index 0a7621bf6..75335cb2b 100644 --- a/doc/tutorial5.md +++ b/doc/tutorial5.md @@ -1,6 +1,6 @@ -[[previous]](tutorial4.md) [[index]](tutorial-index.md) [[next]](tutorial6.md) +# Tutorial - Part 5: Capturing video frames -# Capturing video frames (Tutorial 5) +[[previous]](tutorial4.md) [[index]](tutorial-index.md) [[next]](tutorial6.md) In this tutorial we show how to use a stream to capture a stream of video frames. diff --git a/doc/tutorial6.md b/doc/tutorial6.md index 3b73d3396..127b5e183 100644 --- a/doc/tutorial6.md +++ b/doc/tutorial6.md @@ -1,6 +1,6 @@ -[[previous]](tutorial5.md) [[index]](tutorial-index.md) [[next]](tutorial7.md) +# Tutorial - Part 6: Binding objects -# Binding objects (Tutorial 6) +[[previous]](tutorial5.md) [[index]](tutorial-index.md) [[next]](tutorial7.md) In this tutorial we show how to bind to an object so that we can receive events and call methods on the object.