Skip to content

[demo] Autogenerate documentation on JSON sent to templates/jq from weaver_forge #736

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

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

jsuereth
Copy link
Contributor

@jsuereth jsuereth commented May 10, 2025

This creates a new utility, only intended to be used by weaver contributors, for generating documentation directly from SerDe / schemars configuration. These libraries leverage macros to read our own comments and produce a traversable schema.

UNFORTUNATELY, the schema is optimised for generating JSON schema, so it's actually poor for generating docs. This is ~2 hour attempt at doing something decent enough to evaluate if we want to invest in it. Alternatively, we could use schemars to generate docs and then fire these at an NPM utility that creates markdown from json schema.

Either way the goal of this PR is to:

  • Provide human readable documentation over what JSON fields and types to expect in JQ and JINJA. Note: We can expand to Rego in the future.
  • Provide an easy to run tool that will automatically update these docs when changes are made (via cargo run -p docgen)
  • Discuss what we want human readable documentation to look like and minimum requirements

Towards: #692 and #693

Copy link

@github-advanced-security github-advanced-security bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clippy found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant