Skip to content

Setup/Build tools for generating libweston documentation

Marius Vlad requested to merge mvlad/weston:libweston-doc-breathe into master

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 libweston/doc which adds its own meson.build file such we contain there. Decided ultimately to have the 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 need -Dlibweston-doc=true to be generated. Once we have "some" valid documentation we can remove this. Removed libweston from 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.

  • Need breathe to point to correct XML database generated by doxygen 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 dummy custom_target to 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. This is no longer the case, we use configure_file() to copy the rst files to build dir as the src dir must be immutable when doing the build.

Edited by Marius Vlad

Merge request reports