Uploaded image for project: 'Mender'
  1. Mender
  2. MEN-4107

Document DBus API: autogenerate and integrate with mender-docs

    XMLWordPrintable

    Details

      Description

      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.

      Acceptance criteria:

      • 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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                tranchitella Fabio Tranchitella
                Reporter:
                lluis Lluís Campos
              • Votes:
                0 Vote for this issue
                Watchers:
                3 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Summary Panel