When we were designing the libweston output API, I wrote a design document
as a Phabricator wiki page. Phabricator is no longer accessible so that
information needs to be migrated to a new place. Here I am converting most of
it into libweston Sphinx documentation, particularly pulling in the sequence
diagrams I drew. This should help people understand how libweston output
configuration works.
The diagrams are committed as both MSC source files and rendered PNG files. I
did not bother tinkering with the build to run mscgen automatically and then
with the CI images to install the tool.
The Sphinx configuration need numref explicitly enabled so that figures are
automatically numbered and can be referenced by their number rather than their
whole caption text(!).
The document structure is changed a little better flowing with Output
Management being the overview page and the Heads and Outputs being the API
pages.
First I wrote the struct weston_output and weston_head descriptions in Doxygen
comments in libweston.h, but then in the API page that text would have been
buried somewhere towards the end of the page. So I put that text in ReST
instead where it comes as first on the pages as it should. The doc for the
structs only contain a link to the top of the page. Yes, the comment style in
libweston.h is a little broken. If I left the asterisk there it would show up
as a bullet point in Sphinx. OTOH putting everything from \rst in a single line
did not produce anything.
Because Sphinx cannot look in two places, the images need to be copied into the
build dir too.
mscgen: http://www.mcternan.me.uk/mscgen/
Fixes: https://gitlab.freedesktop.org/wayland/weston/issues/25
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
Use doxygen ingroup command as to show the symbols in the sphinx
documentation.
Include some basic comments and document the exported functions from
timeline.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
This details the logging/debugging framework with the latest changes,
making use of the groups added by "weston-log: Start adding
documentation" and "libweston/log: Add 'wlog' group".
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Destroying the compositor after destroying the log scope will not print
out the messages in the tear down/clean-up phase of the compositor, so
add a new tear_down function which allows keeping a valid reference to
the compositor. This way we can destroy the compositor before destroying
the scope and keep the debug messages.
While at it remove the log context destroy part from the clean-up
of the compositor and make it stand on its own.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Demonstrates how to call/use the 'doxygen*' breathe directives. Make
use of previous patches that tag symbols using 'ingroup' doxygen
command.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
This is adds basic configuration files for doxygen and for breathe,
which is a doxygen-to-sphinx bridge that can document C symbols.
Breathe is configured with default project 'weston' and implicitly adds
:members: and :undoc-members: to breathe configuration options.
This allows a shorter way to call breathe directives without the need
specify the project and also to display implicitly all the members,
documented or not.
A 'docs' run_target to force the docs to be re-built has been added.
Initially (the first time the build system is ran) the documentation
will automatically be built, but later re-builds will require the use of
the 'docs' target. This avoid further delays in building weston but in
the same time allows the possiblity to update/improve the documentation
bits to those who want that.
Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
