Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
W
weston
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 273
    • Issues 273
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
  • Merge Requests 120
    • Merge Requests 120
  • CI / CD
    • CI / CD
    • Pipelines
    • Jobs
    • Schedules
  • Operations
    • Operations
    • Incidents
    • Environments
  • Packages & Registries
    • Packages & Registries
    • Container Registry
  • Analytics
    • Analytics
    • CI / CD
    • Repository
    • Value Stream
  • Members
    • Members
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • wayland
  • weston
  • Issues
  • #216

Closed
Open
Opened Mar 25, 2019 by Marius Vlad@marius.vlad0Reporter

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).
Edited Mar 25, 2019 by Marius Vlad
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information
Assignee
Assign to
None
Milestone
None
Assign milestone
Time tracking
None
Due date
None
Reference: wayland/weston#216