libweston documentation / and the tools to generate it

This issue is about agreeing on the tools/methods to document libweston as to make it more accessible to a broader audience, and obviously make it a little bit easier to understand how to use the library itself to develop, adapt or construct a compositor.

With that in mind I've followed a few directions:

• hotdoc (https://hotdoc.github.io/)
• sphinx (https://www.sphinx-doc.org/en/master/index.html)
  • kerneldoc (https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/kernel-doc?h=v5.1-rc1)
  • sphinx with hawkmoth (https://github.com/jnikula/hawkmoth)
  • sphinx with breathe (https://breathe.readthedocs.io/en/latest/index.html)

The major differences between these two is the fact sphinx is using restructuredText and the tools that parse code follow that (follows rst code documentation tags), while hotdoc uses markdown.

Examples of code generated for each of those

• hotdoc: https://people.collabora.com/~mvlad/libweston-hotdoc/libweston/html/ @ https://gitlab.freedesktop.org/marius.vlad0/weston/tree/libweston-hotdoc
• sphinx w/ kerneldoc: https://people.collabora.com/~mvlad/libweston-sphinx-kerneldoc/ @ https://gitlab.freedesktop.org/marius.vlad0/weston/tree/libweston-sphinx
• sphinx w/ hawkmoth: https://people.collabora.com/~mvlad/libweston-sphinx-hawkmoth/ @ https://gitlab.freedesktop.org/marius.vlad0/weston/tree/libweston-sphinx-hawkmoth
• sphinx w/ breathe: https://people.collabora.com/~mvlad/libweston-sphinx-breathe/ @ https://gitlab.freedesktop.org/marius.vlad0/weston/tree/libweston-sphinx-breathe

Some of the good/bad items I've discovered along the way (at least at this stage):

• hotdoc

  • uses gtkdoc (atm I haven't tested https://github.com/hotdoc/hotdoc_c_extension/tree/master/hotdoc_c_extension) for getting code documentation
  • has meson module from meson 0.48
  • had some issues when installing it, but resolved afterwards
  • gstreamer + meson seems to be the only users
  • forward declarations will not be overwritten by declaration itself and we have a few in compositor.h
  • can't document pointer to functions

• sphinx (kerneldoc)

  • uses kernel-doc script which might be harder to support (is in Linux kernel project -- harder to push things)
  • has the ability to filter by functions, would allow parts of the library being grouped

• sphinx (hawkmoth)

  • one-man project
  • uses clang and all python, much more modern than kerneldoc (and kernel-doc script implicitly)
  • easy to install using pip3 and friends
  • will need improvement if we want \memberof or \addgroup, \ingroup -- that is splitting logically libweston into various parts

• sphinx (breathe)

  • doxygen support ofc
  • minimal changes to current code documentation (which is rather sparse)
  • a bit more heavy on the CPU (the sphinx extension will take some until it parses the XMLS generated by doxygen)
  • grouping (actually rst output) is printed rather ugly imo (the feat is there but it is barely useful).