Solution for genereated Rest API docs

Hey. I was thinking about some approaches for generating restapi (and maybe client bindings) docs in the new docs way.


The fundamental constraint is that pulp-docs should not have to interact with a pulp instance, as we want to keep it simple. The general approach to satisfy that is having the api.json produced and made available as a static file in some automation workflow.


Create a read-only (for humans) repository to serve as the main data source for pulp-docs. My idea is that it uses the current pulp/ repo. It will contain/track:

  • Git submodules of the repositories, which will be updated (as mirrors) by the CI. It should not be touched by humans.

  • Additional artifacts that require custom pre-processing, such as the api.json file or the generated client binding docs. These will be generated by the CI as well.


  • It’s simple and not intrusive to anyone’s workflow.

  • Explicit source of truth of data used for building the docs (easy to inspect).

  • Decouple preparing the data (what set of files we want to be published) from organizing the data (how files will fit together in a mkdocs website), which should make it easier to work on together and reason about.


Dennis suggested generating those extra artifacts on some CI and uploading them to a server, so pulp-docs could independently fetch it. This should work too. My take is that the other approach has more beneficial side-effect, but I’m open to feedback.

1 Like