README: Add a few words about building weston documentation

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>

README.md

@@ -79,6 +79,8 @@ More [detailed documentation on building Weston](https://wayland.freedesktop.org
 is available on the Wayland site. There are also more details on
 [how to run and write tests](https://wayland.freedesktop.org/testing.html).
 
+For building the documentation see [weston-doc](#weston-doc).
+
 Running Weston
 ==============
 
@@ -100,6 +102,41 @@ privileged access to input and output devices by running as root, then granting
 access to the main Weston binary running as your user. Running Weston this way
 is not recommended unless necessary.
 
+Weston-doc
+==========
+
+For documenting weston we use [sphinx](http://www.sphinx-doc.org/en/master/)
+together with [breathe](https://breathe.readthedocs.io/en/latest/) that
+understands XMLs databases generated by doxygen. So far, this is a compromise
+until better tools are available in order to remove the doxygen
+dependency. You should be able to install both sphinx and breathe extension
+using pip3 command, or your package manager.
+Doxygen should be available using your distribution package manager.
+
+Once those are set-up, run `meson` with `-Ddoc=true` option in order to enable
+building the documentation. Installation will place the documentation in the
+prefix's path under datadir (i.e., `share/doc`).
+
+Adding and improving documentation
+----------------------------------
+
+For re-generating the documentation a special `docs` target has been added.
+Although first time you build (and subsequently install) weston, you'll see the
+documentation being built, updates to the spinx documentation files or to the
+source files will only be updated when using `docs` target!
+
+Example:
+
+~~~~
+$ ninja install # generates and installs the documentation
+# time passes, hack hack, add doc in sources or rST files
+$ ninja install # not sufficient, docs will not be updated
+$ ninja docs && ninja install # run 'docs' then install
+~~~~
+
+Improving/adding documentation can be done by modifying rST files under
+`doc/sphinx/` directory or by modifying the source code using doxygen
+directives.
 
 Libweston
 =========