Provide HTML API documentation

[hadess]

The goal would be to generate up-to-date HTML, rich documentation, to consume offline through web browsers or API docs browsers.

Some prior art

bluez using rst2man

https://github.com/bluez/bluez/tree/master/doc

for example: https://github.com/bluez/bluez/blob/master/doc/org.bluez.Device.rst

man page: https://github.com/bluez/bluez/blob/master/client/bluetoothctl.rst

upower, using DocBook + D-Bus Introspection XML:

https://upower.freedesktop.org/docs/

https://upower.freedesktop.org/docs/UPower.html is generated from: https://gitlab.freedesktop.org/upower/upower/-/blob/master/dbus/org.freedesktop.UPower.xml?ref_type=heads

Man page integration: https://upower.freedesktop.org/docs/upower.1.html

xdg-desktop-portal, using gdbus-codegen + sphinx + D-Bus Introspection XML:

https://flatpak.github.io/xdg-desktop-portal/docs/api-reference.html

https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Account.html is generated from: https://github.com/flatpak/xdg-desktop-portal/blob/main/data/org.freedesktop.portal.Account.xml

Man page integration: https://flatpak.github.io/xdg-desktop-portal/docs/portals.conf.html

[Vudentz]

It is actually not that bad if we use github to render the rst it does actually have outline:

And there exist rst2html if we want to generate to web format directly, I guess the main difference is if we want to document directly in code and then generate the documentation via introspection, which is something that perhaps is easier for developers to update when changing the D-Bus APIs, in the other hand I can see the argument that it bloats the code if that is not being auto generated from an interface definition file and I don't expect we change to something like gdbus-codegen anytime soon.

So I think I would favor using rst2html if we ever start publishing documentation.

[pv]

I'd suggest just Sphinx, the output is better than rst2html and it's not any more complicated. I'm not sure there would that much extra value on putting docs in the introspection XML, and bluez doesnt have such files currently

[github-actions[bot]]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[hadess]

I'd suggest just Sphinx, the output is better than rst2html and it's not any more complicated. I'm not sure there would that much extra value on putting docs in the introspection XML, and bluez doesnt have such files currently

Yeah, Sphinx looks like the better option, to be used along with the stylesheets used in xdg-desktop-portal and co. We'd need to see how we can create that D-Bus protocol documentation making sure that the docs match the code.

[hadess]

I've created some HTML docs based on xdg-desktop-portal's code as discussed earlier. This uses meson, sphinx and the aforementioned stylesheets.

Git tree is here: https://github.com/hadess/bluez/tree/wip/hadess/add-docs

An example deployment of the docs is here: https://hadess.github.io/bluez/

We will need to port some documentation text files to RST if we want it to appear in the docs, as it doesn't support referencing .txt files.