Generate an "All Build Items" documentation page #12147
Conversation
gastaldi
force-pushed
the
build_items_doc
branch
from
facdc71 to
d30c121
Compare
| [%header,cols=2*] | ||
| |=== | ||
| |Class Name |Description | ||
| | https://github.com/quarkusio/quarkus/blob/master/extensions/agroal/spi/src/main/java/io/quarkus/agroal/spi/JdbcDriverBuildItem.java[`io.quarkus.agroal.spi.JdbcDriverBuildItem`, window="_blank"] |
There was a problem hiding this comment.
Can the script read the current HEAD and propose that instead of "master"
e.g proposing
- "https://github.com/quarkusio/quarkus/blob/d30c121757d8524a3d5eee6ed2dfcb956a094853/extensions/agroal/spi/src/main/java/io/quarkus/agroal/spi/JdbcDriverBuildItem.java" instead of
- "https://github.com/quarkusio/quarkus/blob/master/extensions/agroal/spi/src/main/java/io/quarkus/agroal/spi/JdbcDriverBuildItem.java"
?
There was a problem hiding this comment.
This way, we could just use the script proposed in the description of this PR to generate this file which will point to source of the latest releases (which is not master since it can contain changes that are not yet released). Moreover, we'll avoid committing this file since it can be generated. Much like what we have now for the configuration reference docs
There was a problem hiding this comment.
Hmmm, not a bad idea. Perhaps something I can provide that in a separate PR. Thanks!
gastaldi
force-pushed
the
build_items_doc
branch
from
d30c121 to
770bf4b
Compare
| | https://github.com/quarkusio/quarkus/blob/master/extensions/agroal/spi/src/main/java/io/quarkus/agroal/spi/JdbcDataSourceSchemaReadyBuildItem.java[`io.quarkus.agroal.spi.JdbcDataSourceSchemaReadyBuildItem`, window="_blank"] | ||
| | +++A build item which can be used to order build processors which need a datasource's schema to be ready (which really means that the tables have been created and any migration run on them) for processing.+++ | ||
| | https://github.com/quarkusio/quarkus/blob/master/extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/AggregatedDataSourceBuildTimeConfigBuildItem.java[`io.quarkus.agroal.deployment.AggregatedDataSourceBuildTimeConfigBuildItem`, window="_blank"] | ||
| | +++<i>No Javadoc found</i>+++ |
There was a problem hiding this comment.
I wonder what can we do with the undocumented items and what can we do about the quality of the existing items? Perhaps as the first step, we should define some guidelines for documenting the BuildItems.
There was a problem hiding this comment.
Yes, something needs to be added to the extension author guide about this.
gastaldi
force-pushed
the
build_items_doc
branch
from
770bf4b to
03dad65
Compare
.github/quarkusbuilditemdoc.java
Outdated
| Path path = Paths.get(line); | ||
| JavaClassSource source = Roaster.parse(JavaClassSource.class, path.toFile()); | ||
| // Ignore deprecated annotations | ||
| if (!source.hasAnnotation(Deprecated.class)) { |
There was a problem hiding this comment.
I think we need to provide inside Quarkus core an annotation to be able to restrict a BuildItem to be listed here, like @NotDocumented or @NotExposed or @Private.
Some build items are designed to be used inside the extension only, and they cannot be made package private always so we need a finer way to control the inclusion in the page.
gastaldi
force-pushed
the
build_items_doc
branch
2 times, most recently
from
fad9045 to
3e5e591
Compare
|
I added the attributes too. Let me know if that looks better before I mark this PR ready to review |
gastaldi
force-pushed
the
build_items_doc
branch
from
3e5e591 to
d47956c
Compare
gastaldi
force-pushed
the
build_items_doc
branch
4 times, most recently
from
df42d15 to
7dbd5b8
Compare
gastaldi
force-pushed
the
build_items_doc
branch
3 times, most recently
from
26ab81f to
8d6205f
Compare
This file is generated by running the following command in the root: ```bash jbang .github/quarkusbuilditemdoc.java --outputFile target/asciidoc/generated/config/quarkus-all-build-items.adoc --dirs core/deployment core/test-extension extensions ``` Fixes quarkusio#9945
gastaldi
force-pushed
the
build_items_doc
branch
from
8d6205f to
c9e2c76
Compare
gastaldi
changed the title
This file is generated by running the following command in the root:
Fixes #9945