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

Updates to the protocol documentation (and its generator) #3747

Merged
merged 4 commits into from
Jul 3, 2024
Merged

Updates to the protocol documentation (and its generator) #3747

merged 4 commits into from
Jul 3, 2024

Commits on Jul 3, 2024

  1. Give <h4> some CSS love in the documentation 

    Our generated proto documentation uses <h4>s but those are not visually
distinct from plain text; increase its size.
    @ethomson
    ethomson committed Jul 3, 2024
    Configuration menu
    Copy the full SHA
    d861731 View commit details
    Browse the repository at this point in the history

  2. Emit well-typed MDX in protocol documentation 

    The generated protocol documentation has a few issues:

1. It creates its own anchors for linking things like request, response,
   and scalar types. However, docusaurus's link checker doesn't know
   about these generated anchors and emits false positives. Instead,
   create React components to generate the titles and anchors, so that
   we can tell docusaurus about these anchors.
2. The links to scalar types assume that we know about all of them. The
   google.protobuf.* types are not documented by us. Create a TypeLink
   component that understands this difference and links to the protobuf
   docs for things like Timestamp.
    @ethomson
    ethomson committed Jul 3, 2024
    Configuration menu
    Copy the full SHA
    e8e931e View commit details
    Browse the repository at this point in the history

  3. Check in generated protocol documentation

    @ethomson
    ethomson committed Jul 3, 2024
    Configuration menu
    Copy the full SHA
    19b74de View commit details
    Browse the repository at this point in the history

  4. Update docs/proto_template.tmpl 

    Co-authored-by: Eleftheria Stein-Kousathana <eleftheria@stacklok.com>
    @ethomson @eleftherias
    ethomson and eleftherias committed Jul 3, 2024
    Configuration menu
    Copy the full SHA
    b79fbe3 View commit details
    Browse the repository at this point in the history