Hey. I was thinking about some approaches for generating restapi (and maybe client bindings) docs in the new docs way.
Problem
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.
Proposal
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/pulpproject.org 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.jsonfile or the generated client binding docs. These will be generated by the CI as well.
Benefits:
-
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.
Alternatives
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.