snazy opened a new pull request, #606:
URL: https://github.com/apache/polaris/pull/606
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-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.
<!--
Possible security vulnerabilities: STOP here and contact
[email protected] instead!
Please update the title of the PR with a meaningful message - do not
leave it "empty" or "generated"
Please update this summary field:
The summary should cover these topics, if applicable:
* the motivation for the change
* a description of the status quo, for example the current behavior
* the desired behavior
* etc
PR checklist:
- Do a self-review of your code before opening a pull request
- Make sure that there's good test coverage for the changes included in
this PR
- Run tests locally before pushing a PR (./gradlew check)
- Code should have comments where applicable. Particularly
hard-to-understand
areas deserve good in-line documentation.
- Include changes and enhancements to the documentation (in
site/content/in-dev/unreleased)
- For Work In Progress Pull Requests, please use the Draft PR feature.
Make sure to add the information BELOW this comment.
Everything in this comment will NOT be added to the PR description.
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
