doc: output management sequence diagrams

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>

1 files changed, 29 insertions, 0 deletions

diff --git a/doc/sphinx/toc/libweston/images/destroy-output.msc b/doc/sphinx/toc/libweston/images/destroy-output.msc
new file mode 100644
index 00000000..fc477fff
--- /dev/null
+++ b/doc/sphinx/toc/libweston/images/destroy-output.msc
@@ -0,0 +1,29 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	--- [label = "Compositor destroys an output for a head"];
+
+	c box c [label = "A head is found disconnected, is being destroyed, or something else needs it disabled."];
+
+	c => w [label = "weston_head_get_output()"];
+	c << w [label = "weston_output"];
+
+	c box c [label = "decide the output needs to be destroyed"];
+
+	c => w [label = "weston_output_destroy()"];
+	w => b [label = "weston_output::destroy()"];
+	w <= b [label = "weston_output_release()"];
+	w <= w [label = "weston_head_detach()"];
+	w :> b [label = "weston_output::detach_head()"];
+	w >> b [label = "release return"];
+	b box b [label = "free(output)"];
+	w << b;
+	c << w;
+}