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 libweston/doc
which adds its own meson.build
file such we contain there.doc/
under root source directory, so we can document other "aspects" like the core-internals
, libweston-desktop
or 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=true
to be generated. Once we have "some" valid documentation we can remove this.libweston
from the name and use directlydoc
(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 usebreathe
to point to correct XML database generated bydoxygen
and in the same time the configuration file for sphinx needs to reside in the same directory. This is problematic and resorted to using a dummycustom_target
to copy the config file from build directory to the source one asconfigure_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.