-
Notifications
You must be signed in to change notification settings - Fork 43
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
Updates to the protocol documentation (and its generator) #3747
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
eleftherias
requested changes
Jul 1, 2024
eleftherias
previously approved these changes
Jul 3, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good now, but there are some merge conflicts
Our generated proto documentation uses <h4>s but those are not visually distinct from plain text; increase its size.
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
force-pushed
the
ethomson/proto_docs
branch
from
July 3, 2024 13:08
7033a5c
to
1685bf6
Compare
rebased on main |
Co-authored-by: Eleftheria Stein-Kousathana <eleftheria@stacklok.com>
ethomson
force-pushed
the
ethomson/proto_docs
branch
from
July 3, 2024 13:18
1685bf6
to
b79fbe3
Compare
eleftherias
approved these changes
Jul 3, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Running
docusaurus build
generates warnings on the generated protocol documentation, most are false positives, but three are correct (which were buried by the other false positives).The false positives arise because we use our 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. This PR updates the generator to instead create React components to generate the titles and anchors, so that we can tell docusaurus about them. Its link checker will then not emit a false positive.
Then, the links to the types assume that we document all of them on this page. But 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 likeTimestamp
.Change Type
Mark the type of change your PR introduces:
Testing
Run
npm run build
in thedocs
folder and ensure that there are no warnings.Review Checklist: