doc: switch from .md to .dox files and impose some general structure

This is an attempt of breaking up the documentation, currently spread across
several pages. We're left with a few high-level topics with various things
grouped underneath those.

Further refinement is necessary, but this can now be done in incremental steps
over massive reworks.

doc/api.dox

@@ -0,0 +1,8 @@
+/** \page page_api API Documentation
+
+The API consists of two parts:
+
+- The \subpage page_core_api to access a PipeWire instance.
+- The \subpage page_implementation_api and tools to build new objects and modules
+
+*/

doc/index.dox

@@ -0,0 +1,35 @@
+/** \mainpage PipeWire
+
+PipeWire is low-level multimedia framework that provides:
+  - Graph based processing
+  - Support for out-of-process processing graphs with minimal overhead
+  - Flexible and extensible media format negotiation and buffer allocation
+  - Hard real-time capable plugins
+  - Very low-latency for both audio and video processing
+
+See \ref page_overview for an overview of PipeWire and \ref page_design
+for the design principles guiding PipeWire.
+
+### Components
+
+PipeWire ships with the following components:
+
+- a \ref page_daemon that implements the IPC and graph processing
+- an example \ref page_session_manager that manages objects in the \ref page_daemon
+- a set of \ref page_tools to introspect and use the \ref page_daemon
+- a \ref page_library to develop PipeWire applications and plugins (\ref
+  page_tutorial "tutorial").
+- the \ref page_spa used by both the \ref page_daemon and in the \ref
+  page_library.
+
+### API Documentation
+
+See \ref page_api
+
+
+### Resources
+
+* [LAC 2020 Paper](https://lac2020.sciencesconf.org/307881/document)
+
+
+*/

doc/index.md

@@ -1,16 +0,0 @@
-# PipeWire Documentation
-
-Start with the [overview](overview.md) of PipeWire.
-
-Some notes about the [architecture](architecture.md) can be
-found here.
-
-Start the tutorial about how to use the PipeWire API
-[here](tutorial-index.md).
-
-Notes about the design of the low-level [SPA](spa-design.md)
-layer.
-
-Some Resources:
-
-* [LAC 2020 Paper](https://lac2020.sciencesconf.org/307881/document)

doc/meson.build

@@ -43,11 +43,18 @@ else
   spa_strip_static = []
 endif
 
+# Note: order here is how doxygen will expose the pages in the sidebar
 extra_docs = [
-  'pipewire-overview.md',
-  'pipewire-design.md',
-  'pipewire-architecture.md',
-  'pipewire-objects-design.md',
+  'index.dox',
+  'pipewire.dox',
+  'pipewire-overview.dox',
+  'pipewire-design.dox',
+  'pipewire-daemon.dox',
+  'pipewire-library.dox',
+  'pipewire-tools.dox',
+  'pipewire-session-manager.dox',
+  'pipewire-objects-design.dox',
+  'api.dox',
   'tutorial.dox',
   'tutorial1.dox',
   'tutorial2.dox',
@@ -59,7 +66,7 @@ extra_docs = [
   'spa-design.dox',
   'spa-pod.dox',
   'spa-buffer.dox',
-  'pulseaudio.md',
+  'pulseaudio.dox',
 ]
 
 foreach extra : extra_docs

doc/pipewire-daemon.dox

@@ -0,0 +1,43 @@
+/** \page page_daemon PipeWire Daemon
+
+
+\section sec_logging Logging
+
+The `PIPEWIRE_DEBUG` environment variable can be used to enable
+more debugging. The format is:
+
+`<level>[<category>;...]`
+
+- `<level>` specifies the log level:
+  + `0`: no logging is enabled
+  + `1`: Error logging is enabled
+  + `2`: Warnings are enabled
+  + `3`: Informational messages are enabled
+  + `4`: Debug messages are enabled
+  + `5`: Trace messages are enabled. These messages can be logged
+     	from the realtime threads.
+
+- `<category>`:  Specifies a string category to enable. Many categories
+     	  can be separated by commas. Current categories are:
+  + `connection`: to log connection messages
+
+
+\subsection sec_errors Error reporting
+
+Functions return either NULL with errno set or a negative int error
+code when an error occurs. Error codes are used from the SPA plugin
+library on which PipeWire is built.
+
+Some functions might return asynchronously. The error code for such
+functions is positive and SPA_RESULT_IS_ASYNC() will return true.
+SPA_RESULT_ASYNC_SEQ() can be used to get the unique sequence number
+associated with the async operation.
+
+The object returning the async result code will have some way to
+signal the completion of the async operation (with, for example, a
+callback). The sequence number can be used to see which operation
+completed.
+
+
+
+*/

doc/pipewire-design.dox

@@ -1,5 +1,4 @@
-PipeWire
---------
+/** \page page_design PipeWire Design
 
 PipeWire is a media server that can run graphs of multimedia nodes.
 Nodes can run inside the server or in separate processes.
@@ -69,3 +68,5 @@ Some of the extensions that can be written
  - a module to automatically create or link or relink nodes
 
  - a module to suspend idle nodes
+
+*/

doc/pipewire-library.dox

@@ -1,4 +1,4 @@
-# PipeWire Architecture
+/** \page page_library PipeWire Library
 
 There are 2 main components that make up the PipeWire library:
 
@@ -34,7 +34,7 @@ described in an external protocol file but implemented directly in
 a protocol plugin. Protocol plugins can be added to add new
 objects or even protocols when required.
 
-Messages are encoded with [SPA PODs](spa-pod.md), which make it
+Messages are encoded with \ref page_spa_pod, which make it
 possible to encode complex objects with right types.
 
 Events from the server can be a reply to a method or can be emitted
@@ -219,3 +219,6 @@ data unless they can see the objects and connect to them.
 
 PipeWire also exposes an API to implement the server side objects in
 a graph.
+
+*/
+

doc/pipewire-objects-design.dox

@@ -1,4 +1,4 @@
-# PipeWire Objects Design
+/** \page page_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
@@ -329,3 +329,5 @@ JACK server as a client is out of scope here.
 
 JACK clients do not create endpoints. A session manager should be JACK aware
 in order to anticipate direct node linking
+
+*/

doc/pipewire-overview.dox

@@ -0,0 +1,42 @@
+/** \page page_overview PipeWire Overview
+
+PipeWire is a new low-level multimedia framework designed from scratch that
+aims to provide
+
+- graph based processing
+- support for out-of-process processing graphs with minimal overhead
+- flexible and extensible media format negotiation and buffer allocation
+- Hard real-time capable plugins
+- achieve very low-latency for both audio and video processing
+
+The framework is used to build a modular daemon that can be configured to:
+
+- be a low-latency audio server with features like pulseaudio and/or jack
+- a video capture server that can manage hardware video capture devices and
+  provide access to them
+- a central hub where video can be made available for other applications
+  such as the gnome-shell screencast API.
+
+
+## Motivation
+
+Linux has no unified framework for exchanging multimedia content between
+applications or even devices. In most cases, developers realized that
+a user-space daemon is needed to make this possible:
+
+- For video content, we typically rely on the compositor to render our
+  data.
+- For video capture, we usually go directly to the hardware devices, with
+  all security implications and inflexible routing that this brings.
+- For consumer audio, we use PulseAudio to manage and mix multiple streams
+  from clients
+- For Pro audio, we use JACK to manage the graph of nodes.
+
+None of these solutions (except perhaps to some extent Wayland), however,
+were designed to support the security features that are required when
+dealing with flatpaks or other containerized applications. PipeWire
+aims to solve this problem and provides a unified framework to run both
+consumer and Pro audio as well as video capture and processing in a
+secure way.
+
+*/

doc/pipewire-overview.md

@@ -1,58 +0,0 @@
-# PipeWire Overview
-
-PipeWire is a new low-level multimedia framework designed from scratch that
-aims to provide
-
-* graph based processing
-* support for out-of-process processing graphs with minimal overhead
-* flexible and extensible media format negotiation and buffer allocation
-* Hard real-time capable plugins
-* achieve very low-latency for both audio and video processing
-
-The framework is used to build a modular daemon that can be configured to:
-
-* be a low-latency audio server with features like pulseaudio and/or jack
-* a video capture server that can manage hardware video capture devices and
-  provide access to them
-* a central hub where video can be made available for other applications
-  such as the gnome-shell screencast API.
-
-## Motivation
-
-Linux has no unified framework for exchanging multimedia content between
-applications or even devices. In most cases, developers realized that
-a user-space daemon is needed to make this possible:
-
-* For video content, we typically rely on the compositor to render our
-  data.
-* For video capture, we usually go directly to the hardware devices, with
-  all security implications and inflexible routing that this brings.
-* For consumer audio, we use PulseAudio to manage and mix multiple streams
-  from clients
-* For Pro audio, we use JACK to manage the graph of nodes.
-
-None of these solutions (except perhaps to some extent Wayland), however,
-were designed to support the security features that are required when
-dealing with flatpaks or other containerized applications. PipeWire
-aims to solve this problem and provides a unified framework to run both
-consumer and Pro audio as well as video capture and processing in a
-secure way.
-
-
-## Components
-
-Currently PipeWire ships with the following components:
-
-* a PipeWire daemon that implements the IPC and graph processing
-* an example session manager that manages objects in the PipeWire
-  daemon.
-* a set of tools to introspect and use the PipeWire daemon.
-* a library to develop PipeWire applications and plugins.
-
-### The PipeWire daemon
-
-### The example session manager
-
-### Tools
-
-### Application development

doc/pipewire-session-manager.dox

@@ -0,0 +1,4 @@
+/** \page page_session_manager PipeWire Session Manager
+
+*/
+

doc/pipewire-tools.dox

@@ -0,0 +1,4 @@
+/** \page page_tools PipeWire Tools
+
+*/
+

doc/pipewire.dox

@@ -0,0 +1,25 @@
+/** \page page_pipewire PipeWire
+
+## Internals
+
+- \subpage page_overview
+- \subpage page_design
+- \subpage page_streams
+- \subpage page_client
+- \subpage page_proxy
+- \subpage page_thread_loop
+- \subpage page_objects_design
+
+## Components
+
+- \subpage page_daemon
+- \subpage page_library
+- \subpage page_tools
+- \subpage page_session_manager
+- \ref page_spa
+
+## Backends
+
+- \subpage page_pulseaudio
+
+*/

doc/pulseaudio.dox

@@ -1,3 +1,5 @@
+/** \page page_pulseaudio  PulseAudio compatibility
+
 # Internals - Mapping between ALSA and streams
 
 This explains the mapping between alsa cards and streams and session manager
@@ -66,3 +68,5 @@ the endpoint. This clashes with the notion that multiple streams can be
 active at the same time but is a pulseaudio limitation.
 
 Each Endpoint destination becomes a port on the sink/source.
+
+*/

doc/tutorial.dox

@@ -1,4 +1,4 @@
-/** \page page_tutorial Tutorial - The PipeWire API
+/** \page page_tutorial Tutorial
 
 Welcome to the PipeWire tutorial. The goal is to learn
 PipeWire API step-by-step with simple short examples.

src/pipewire/pipewire.h

@@ -60,55 +60,6 @@ extern "C" {
 #include <pipewire/utils.h>
 #include <pipewire/version.h>
 
-/** \mainpage
- *
- * \section sec_intro Introduction
- *
- * This document describes the API for the PipeWire multimedia framework.
- * The API consists of two parts:
- *
- * \li The core API to access a PipeWire instance.
- * (See \subpage page_core_api)
- * \li The implementation API and tools to build new objects and
- * modules (See \subpage page_implementation_api)
- *
- * \section sec_errors Error reporting
- *
- * Functions return either NULL with errno set or a negative int error
- * code when an error occurs. Error codes are used from the SPA plugin
- * library on which PipeWire is built.
- *
- * Some functions might return asynchronously. The error code for such
- * functions is positive and SPA_RESULT_IS_ASYNC() will return true.
- * SPA_RESULT_ASYNC_SEQ() can be used to get the unique sequence number
- * associated with the async operation.
- *
- * The object returning the async result code will have some way to
- * signal the completion of the async operation (with, for example, a
- * callback). The sequence number can be used to see which operation
- * completed.
- *
- * \section sec_logging Logging
- *
- * The `PIPEWIRE_DEBUG` environment variable can be used to enable
- * more debugging. The format is:
- *
- * `<level>[<category>;...]`
- *
- * - `<level>` specifies the log level:
- *   + `0`: no logging is enabled
- *   + `1`: Error logging is enabled
- *   + `2`: Warnings are enabled
- *   + `3`: Informational messages are enabled
- *   + `4`: Debug messages are enabled
- *   + `5`: Trace messages are enabled. These messages can be logged
- *		from the realtime threads.
- *
- * - `<category>`:  Specifies a string category to enable. Many categories
- *		  can be separated by commas. Current categories are:
- *   + `connection`: to log connection messages
- */
-
 /** \defgroup pw_pipewire PipeWire initialization and infrastructure functions
  */