build: Add sphinx/breathe support for generating documentation

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>

doc/sphinx/toc/libweston/compositor.rst

@@ -0,0 +1,7 @@
+Compositor
+==========
+
+:type:`weston_compositor` represents the core object of the library, which
+aggregates all the other objects and maintains their state. You can create it
+using :func:`weston_compositor_create`, while for destroying it and releasing all
+the resources associated with it, you should use :func:`weston_compositor_destroy`.

doc/sphinx/toc/libweston/head.rst

@@ -0,0 +1,18 @@
+Head
+====
+
+A head usually refers to a monitor, but it can also refer to an output window
+in case of a nested compositor. A :type:`weston_output` is responsible for
+driving a :type:`weston_head`. :type:`weston_head` should be initialized using
+:func:`weston_head_init`, and shall be released using
+:func:`weston_head_release`.
+
+.. note::
+
+   :func:`weston_head_init` and :func:`weston_head_release` belong to the
+   private/internal backend API and should be moved accordingly once that
+   section has been created.
+
+A :type:`weston_head` must be attached/detached from a :type:`weston_output`.
+To that purpose you can use :func:`weston_output_attach_head`, respectively
+:func:`weston_head_detach`.

doc/sphinx/toc/libweston/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+files = [ 'compositor.rst', 'head.rst', 'output.rst' ]
+
+foreach file : files
+	configure_file(input: file, output: file, copy: true)
+endforeach

doc/sphinx/toc/libweston/output.rst

@@ -0,0 +1,10 @@
+Output
+======
+
+With at least a :type:`weston_head` attached, you can construct a
+:type:`weston_output` object which can be used by the compositor, by enabling
+the output using :func:`weston_output_enable`. The output **must not** be
+already enabled.
+
+The reverse operation, :func:`weston_output_disable`, should be used when there's
+a need to reconfigure the output or it will be destroyed.