openlab-cli
openlab-cli copied to clipboard
improvement: automated docs rendering
Background
A set of tools to generate documentation was introduced in #21:
- structured JSON CLI interface spec (via
@labdao/oclif-plugin-helpdataandnpm run docs:mkjson) - a README generation script (via
oclif readmeandnpm run docs:readme)
Goal
An efficient, reliable, and secure documentation pipeline.
This will require:
- that there is one source of truth for the documentation
- the source for documentation lives alongside the code
- the documentation intended for user consumption can be automatically generated and verified
This will achieve:
- Docs that are (more likely to be) always up to date with the code because they are generated automatically, and can easily be included in code review and publishing processes.
- Minimal barrier to contribution because there's a single place to work on documentation.
- A reduced attack surface for the documentation of the project because the docs can be subject to automated consistency testing and can follow the same security protocols as the code.
Proposal
We should use the structured interface spec to generate and render the documentation website for openlab-cli.
Specifically, we should use the docs/cli.api.json spec generated by npm run docs:mkjson to render .mdx files for the interface and tutorials, as well as the README, and any other reference sources we need.
Nunjucks is a very simple and reilable solution that can be used for the remplate rendering.