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.rst

@@ -0,0 +1,46 @@
+Libweston
+=========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   libweston/compositor.rst
+   libweston/head.rst
+   libweston/output.rst
+
+`Libweston` is an effort to separate the re-usable parts of Weston into a
+library. `Libweston` provides most of the boring and tedious bits of correctly
+implementing core Wayland protocols and interfacing with input and output
+systems, so that people who just want to write a new "Wayland window manager"
+(WM) or a small desktop environment (DE) can focus on the WM part.
+
+Libweston was first introduced in Weston 1.12, and is expected to continue
+evolving through many Weston releases before it achieves a stable API and
+feature completeness.
+
+`Libweston`'s primary purpose is exporting an API for creating Wayland
+compositors. Libweston's secondary purpose is to export the weston_config API
+so that third party plugins and helper programs can read :file:`weston.ini` if
+they want to. However, these two scopes are orthogonal and independent. At no
+point will the compositor functionality use or depend on the weston_config
+functionality.
+
+Further work
+------------
+
+In current form, `libweston` is an amalgam of various APIs mashed together and
+currently it needs a large clean-up and re-organization and possibly, a split
+into class-specific files. The documentation only provide the public
+API and not the private API used inside `libweston` or other functionality
+required in the core internals of the library.
+
+With that in mind we see the following steps needed to achieve that:
+
+- migrate everything that should not reside in the public API (for instance,
+  the doxygen **\\internal** command is a clear indication that that symbol
+  should not be present in the public API) to private headers.
+- if needed be, create class-specific files, like **input** and **output**
+  which should tackle specific functionality, and allows to write the
+  documentation parts much easier, and provides clarity for `libweston`
+  users when they'd read it.

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.

doc/sphinx/toc/meson.build

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