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.

Sign up for GitHub

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

Jump to bottom

Generate spec docs from a YAML source file #1588

Merged
merged 6 commits into from
Mar 29, 2023
Merged

Generate spec docs from a YAML source file #1588

merged 6 commits into from
Mar 29, 2023

Commits on Mar 27, 2023

  1. Initial support for automatic spec doc generation 

    Move all field descriptions to a single YAML file and generate version-
specific spec docs from that.  Use reflection to walk the config
structs for each version and omit fields which don't exist in a
particular spec version.

We don't do this at a JSON Schema level because e.g. Resource is
referenced in multiple places with different semantics and different
doc strings.

For now, keep the code out of the external API.  The plan is to add
functionality to support Butane docs generation, at which point
internal/doc/generate will move to config/doc.

Update the stabilization checklist to remove manual tweaking of
spec docs.
    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    1989f24 View commit details
    Browse the repository at this point in the history

  2. internal/doc: re-add header to spec docs

    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    f7aac9e View commit details
    Browse the repository at this point in the history

  3. internal/doc: support string replacements on specific spec versions

    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    ad540ac View commit details
    Browse the repository at this point in the history

  4. internal/doc: allow substituting spec version into generated doc

    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    de75e46 View commit details
    Browse the repository at this point in the history

  5. docs: regenerate spec docs 

    Move link URLs inline and fix various small errors.

Fixes #1469.
    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    379d481 View commit details
    Browse the repository at this point in the history

  6. internal/doc: remove previous experimental doc during stabilization

    @bgilbert
    bgilbert committed Mar 27, 2023
    Configuration menu
    Copy the full SHA
    f86b410 View commit details
    Browse the repository at this point in the history