Setup/Build tools for generating libweston documentation
This adds support for starting to build documentation for libweston. There's no documentation per-se at the moment, and it will require some code re-arrangement and some prose to be added initially before actually adding some real doc.
See #216 (closed) for a more thorough explanation on why we choose sphinx and breathe as bridge for/to doxygen.
The patches/series are quite voluminous due to initial doxygen and sphinx config files.
I can remove the comments in doxygen if that's a requirement.
Added subdirectory in Decided ultimately to have the
which adds its own
meson.build file such we contain there.
doc/ under root source directory, so we can document other "aspects" like the
ivi-shell, and potentially many more.
Some of the issues I've discovered with toying it:
Noticed that newer pip version of breathe do not play nicely with sphinx 1.8 so I've added some rather naive checks to verify the version for it. Of course this only takes into account pip3 installed version(s) so those installed by the package manager will not play nicely. Waiting for feedback on this front if this is alright or not.Pinned to specific version, seems that the issues was due to using sphinx from package manager and breathe more
At this stage, it is not enabled by default it will needRemoved
-Dlibweston-doc=trueto be generated. Once we have "some" valid documentation we can remove this.
libwestonfrom the name and use directly
doc(as we're documenting the compositor not just the library used to build on it. This has been enabled by default in CI.
NeedThis is no longer the case, we use
breatheto point to correct XML database generated by
doxygenand in the same time the configuration file for sphinx needs to reside in the same directory. This is problematic and resorted to using a dummy
custom_targetto copy the config file from build directory to the source one as
configure_file()can't be "instructed" to place the config file where we need it.
configure_file()to copy the rst files to build dir as the src dir must be immutable when doing the build.