Tool to generate configuration reference docs#606
Merged
snazy merged 2 commits intoapache:mainfrom Jan 13, 2025
Merged
Conversation
snazy
requested review from
RussellSpitzer,
adutra,
ashvina,
collado-mike,
ebyhr,
eric-maynard,
flyrain,
jackye1995,
jbonofre,
takidau and
vvcephei
as code owners
snazy
force-pushed
the
cfg-ref-doc-gen
branch
from
48ec569 to
64eed98
Compare
dimas-b
reviewed
Jan 13, 2025
gradle/projects.main.properties
Outdated
Contributor
There was a problem hiding this comment.
nit: IMHO the name ref-config looks a bit awkward... How about tools/config-doc?
Contributor
There was a problem hiding this comment.
nit: IntOne makes me think of integer 1 :) Maybe InterfaceOne?
Having documentation about the configuration that is both "up-to-date" and "in-sync with the source code" with the actual code is good practice. The functionality added in this change allows generating markdown docs from smallrye-config based configuration types, starting at and grouped by types that are annotated with `@ConfigMapping`. The javadoc of the config interfaces and properties is emitted as markdown. On top there is functionality to generate reference docs for "static" types (currently unused in Polaris). The code is nearly a 1:1 port of the same functionality in Nessie. This change will become useful with/after apache#469. Gradle projects added in this change are: * `polaris-config-doc-annotations` adds an annotation used when generating docs to influence the generation of the configuration reference docs. * `polaris-config-doc-generator` is the reference doc generator implementation, as a "standalone" tool that uses javadoc _infrastructure_. See `ReferenceConfigDocsGenerator` why it needs to be a separate tool than "just" a doclet (class loader isolation issues). * `polaris-site-reference-docs` actually generates the markdown files from referenced Gradle projects. Currently there are no projects referenced, so generation yields nothing. The generated docs are not yet integrated into the website, which will happen in a follow-up PR.
snazy
force-pushed
the
cfg-ref-doc-gen
branch
from
64eed98 to
1ac6462
Compare
dimas-b
approved these changes
Jan 13, 2025
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Having documentation about the configuration that is both "up-to-date" and "in-sync with the source code" with the actual code is good practice.
The functionality added in this change allows generating markdown docs from smallrye-config based configuration types, starting at and grouped by types that are annotated with
@ConfigMapping. The javadoc of the config interfaces and properties is emitted as markdown. On top there is functionality to generate reference docs for "static" types (currently unused in Polaris).The code is nearly a 1:1 port of the same functionality in Nessie. This change will become useful with/after #469.
Gradle projects added in this change are:
polaris-config-doc-annotationsadds an annotation used when generating docs to influence the generation of the configuration reference docs.polaris-config-doc-generatoris the reference doc generator implementation, as a "standalone" tool that uses javadoc infrastructure. SeeReferenceConfigDocsGeneratorwhy it needs to be a separate tool than "just" a doclet (class loader isolation issues).polaris-site-reference-docsactually generates the markdown files from referenced Gradle projects. Currently there are no projects referenced, so generation yields nothing.The generated docs are not yet integrated into the website, which will happen in a follow-up PR.