We will autogenerate a markdown description of our docs using gdbus-codegen. A post-process step is required to further refine the output.
The goal is to generate something similar to this: https://core.docs.ubuntu.com/en/stacks/location/location-service/docs/reference/dbus-api
The markdown documentation is generated in two steps:
- gdbus-codegen to generate a doc book. See Lluís PoC command here.
- pandoc to generate the markdown. See Lluís PoC command here.
The post-processing steps required are:
- XML: refsynopsisdiv -> refsect1
- XML: remove refmeta (leading com.mender.Authentication1)
- MD: Add H1 marker to Authentication API v1
- MD: Header methods/signals as a list with links to below
Experimenting with the PoC is recommended to get familiar with these clean-ups.
- mender-docs has a new page for DBbus API docs
- Where? TBD
- mender-docs-site has a tool/script to do the post-processing of the DBus API spec files
- mender-docs-site logic is extended to fetch, convert, post-process DBus API documetation from mender repository and insert it into mender-docs corresponding content page
- mender pipeline has a job to trigger mender-docs-site on changes to the spec files, similar to the backend API process