Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

improvement: automated docs rendering #52

Open
blahah opened this issue Jul 5, 2022 · 0 comments
Open

improvement: automated docs rendering #52

blahah opened this issue Jul 5, 2022 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@blahah
Copy link
Contributor

blahah commented Jul 5, 2022

Background

A set of tools to generate documentation was introduced in #21:

  • structured JSON CLI interface spec (via @labdao/oclif-plugin-helpdata and npm run docs:mkjson)
  • a README generation script (via oclif readme and npm 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:

  1. 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.
  2. Minimal barrier to contribution because there's a single place to work on documentation.
  3. 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.

@blahah blahah added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 5, 2022
@blahah blahah self-assigned this Jul 5, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant