From 1bc6ceba0661c4e6a509a3f0b34cc70105284a03 Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Wed, 5 Jun 2019 13:29:16 +0300 Subject: [PATCH] README: Add a few words about building weston documentation Signed-off-by: Marius Vlad --- README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/README.md b/README.md index 7f686d99f..bd701b9aa 100644 --- a/README.md +++ b/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 =========