feat: Infrastructure for generating protobuf docs #6046
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
alexpeters1208
requested review from
devinrsmith,
jcferretti and
rcaudy
as code owners
alexpeters1208
changed the title
devinrsmith
reviewed
Sep 10, 2024
There was a problem hiding this comment.
I think we should take the approach of generating the documentation as part of proto/proto-backplane-grpc/Dockerfile; as such, there will probably be a /generated/proto-doc/ directory that will need to be created with appropriate configuration and artifacts specified in proto/proto-backplane-grpc/build.gradle.
chipkent
reviewed
Sep 10, 2024
devinrsmith
requested changes
Sep 10, 2024
devinrsmith
previously approved these changes
Sep 11, 2024
There was a problem hiding this comment.
This PR successfully builds the proto documentation:
$ ./gradlew proto:proto-backplane-grpc:build
...
$ tree proto/proto-backplane-grpc/build/generated/source/proto/main/proto-doc
proto/proto-backplane-grpc/build/generated/source/proto/main/proto-doc
├── application.md
├── config.md
├── console.md
├── hierarchicaltable.md
├── inputtable.md
├── object.md
├── partitionedtable.md
├── session.md
├── storage.md
├── table.md
└── ticket.md
1 directory, 11 files
A couple of notes:
- We aren't doing anything with these docs right now (not adding them as release artifacts, uploading to the docs site, etc); I'm assuming that is "ok"?
- By splitting up the markdown files, I don't think we are getting proper linking between them. For example, stuff in table.proto depends on stuff in ticket.proto; but the separate markdown files are unable to capture that afaict.
alexpeters1208
added
ReleaseNotesNeeded
chipkent
reviewed
Sep 11, 2024
chipkent
previously approved these changes
Sep 11, 2024
devinrsmith
reviewed
Sep 11, 2024
devinrsmith
approved these changes
Sep 11, 2024
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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.
This adds Docker instructions and a Gradle configuration to generate markdown documentation for Protobuf files at
proto/proto-backplane-grpc/build/generated/source/proto/main/proto-doc. The new docs get generated as a part of the./gradlew :proto:proto-backplane-grpc:generateProtobufGradle task. We should assess whether flight should receive the same treatment.