Don't show page sections in left sidebar, it's confusing.
Rename Modules -> API Reference in sidebar.
Indicate visually the sidebar entries are collapsible.
Fix spa_pod_json grouping.
Move tools page to top level.
Fix page ordering.
Currently, doxygen is run by ninja in the top-level build directory,
therefore the "doc" folder is always created there. However, when
pipewire is built as a subproject, it should not touch the top-level
build directory because it can cause conflicts and because the
documentation won't be created where meson thinks it will be,
so the "doxygen" target will always be dirty and installation will fail.
Use `meson.project_{build,source}_root()` instead of
`meson.{build,source}_root()` because those functions
do not work as expected when used inside a subproject,
and they have been deprecated in meson 0.56.0.
The Doxygen "Modules" page is not very illuminative, as different parts
of the API are mixed together and not all parts are included.
Try to address this:
Put all parts of the public API to some Doxygen group, usually one group
per header file. Use short, systematic names.
Make these groups sub-groups of a few top-level groups, roughly
corresponding to the different logical parts of the API (core, impl,
stream, filter, spa, utilities).
Add an input filter that tries to link e.g.
#define pw_core_add_listener(...) pw_core_method(c,add_listener,...)
to the corresponding declaration in struct pw_core_methods.
Make Doxygen data structure etc. lists less cluttered by hiding
non-public stuff.
Add a Doxygen input filter that marks symbols declared in C files
private, so that they won't appear in the output unless the symbol is
also declared in a header.
The "spa static inline" hack is then also not needed any more.
This adds a new top-level documentation entry for pipewire-media-session
with a list of modules (currently only one). Similar setup to the
pipewire modules, it allows us to document all modules in-place.
This is a good first (top) page to have in the docs, let's move it out
from the pipewire heading.
This doesn't change any of the links and the renaming isn't required
(subpage controls whether it's a top-level item and the meson.build
order decides its spot in he list). Still, better to have the filenames
represent the layout.
Add more info to the main SPA page and split the design vs plugin pages up,
together with some more documentation to ideally lower make this easier to
understand on a glance.
Most of the actual plugin loading documentation are unmodified.
Heavily inspired by libinput's litest framework (built around check), this is
a from-scratch framework that simplifies adding tests for various parts of
pipewire. See the pwtest.h documentation for details but the basics are:
- PW_TEST() and PWTEST_SUITE() specify the tests to be run
- Test are run in forked processes, any errors/signals are caught and printed
to the log
- Tests have a custom pipewire daemon started on demand to talk to [1]. The
daemon's log is available in the test output.
- Output is YAML to be processed into whatever format needed
[1] There are limits here, since we can't emulate devices yet there is only
so much we can rely on with the daemon.
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.
While doxygen can handle markdown pages, support for it is very limited:
markdown pages can only be included as a whole page, they get an automatic
title (custom titles are possible but aren't standard markdown) and it's not
possible to use \subpage without messing with the markdown again. Any markdown
page will thus end up as separate item in the doxygen output, not really
suitable for generating a good page hiearchy.
Let's switch the tutorial to use doxygen directly instead of markdown, short
of using code/endcode instead of markdown's ``` there isn't that much
difference anyway but it allows us to structure things nicer in the online
docs.
This requires a helper script: doxygen doesn't differ between static methods
and static inline methods. EXTRACT_STATIC defines whether it parses *any*
static method but we're currently using all C files as input files as well. We
cannot convince doxygen to just parse static inline functions in header files
so for SPA we hack around this: meson passes the spa headers to a shell script
with simply copies those changed to `/* static */ inline void (foo)` and doxygen
then runs on those header files.
The result: we get all spa functions added to your doxygen output at the cost
of a few sed calls.
Theme from doxygen-awesome-css with custom modifications based on the
pipewire.org website to use the same type of blue, grey, etc.
doxygen-awesome-css is MIT licensed, see
https://github.com/jothepro/doxygen-awesome-css
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.
Keep all files as strings in an array so we can add them to the custom command
input list - this way meson will correctly rebuild documentation on changes.
