Add support for Asciidoc in configuration reference documentation #3887
Conversation
Repository update - https://github.com/machi1990/quarkus-generated-extension-config-docs/blob/master/src/main/asciidoc/generated/quarkus-hibernate-orm.adoc
Good thing you attached screenshots. GH did not like the icons :-P |
| * | ||
| * `drop-and-create` is awesome in development mode. | ||
| * | ||
| * Accepted values: `none`, `create`, `drop-and-create`, `drop`, `update`. The default is `none`. | ||
| */ | ||
| @ConfigItem |
There was a problem hiding this comment.
Maybe add a defaultValue="none" to the annotation so that it is nicely added to the summary table :-)
There was a problem hiding this comment.
Yes, I have to tweak things a bit regarding that. And wondering if we could use the enum directly now but I have to test it. It's on my list of things to improve.
There was a problem hiding this comment.
Yup, I'm just not sure it will fly, I need to check it and wanted this PR out of the door.
I will fix the default value though. Small improvements are better than later improvements :).
There was a problem hiding this comment.
Done for the default value.
gsmet
force-pushed
the
asciidoclet-support
branch
from
4b74aba
to
8fdba11
Compare
gsmet
force-pushed
the
asciidoclet-support
branch
from
8fdba11
to
dd9d561
Compare
| * Valid values are: none, first, last. | ||
| * Default precedence of null values in `ORDER BY` clauses. | ||
| * | ||
| * Valid values are: `none`, `first`, `last`. |
There was a problem hiding this comment.
Shouldn't we replace this String type with an enum?
There was a problem hiding this comment.
Sure, see the discussion with Manyanda above. But I need to check if we can use an ORM one or if we have to create a new one so I consider it outside of the scope of this PR whose main purpose is to validate the Asciidoc support.
There was a problem hiding this comment.
Ah sorry I didn't see it. Sure it can come in another PR.
...ate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmConfig.java
Outdated
Show resolved
Hide resolved
|
I improved the output a bit by adding a light separator between each entry of the detailed output. Things are far more readable this way. |
tracking progress repo updated |
Asciidoc comment are passthrough but we needed to restructure the parser to enable proper parsing.
This way, it's properly documented.
The Javadoc parser we use uses platform specific EOL characters. This should fix the Windows CI failure.
Note that we will have to tweak the website CSS to keep it light.
gsmet
force-pushed
the
asciidoclet-support
branch
from
93a69b9
to
f5b64f1
Compare
The space just after the star is kept by the javax.lang.model API so let's remove it.
We can't have the generated files in docs/target as it is cleaned prior to generating the documentation when doing a mvn clean install. Fixes quarkusio#3909
|
Boom, its in! |
following quarkusio#3909 docs are now generated in the global /target/ folder and not in docs/src/main/asciidoc/generated. See this comment quarkusio#3909 (comment) and corresponding PR quarkusio#3887
following quarkusio#3909 docs are now generated in the global /target/ folder and not in docs/src/main/asciidoc/generated. See this comment quarkusio#3909 (comment) and corresponding PR quarkusio#3887
/cc @emmanuelbernard @FroMage @machi1990
Here it is. It's a bit more than a one liner as I had to restructure the parser and the output a bit. It fixes a logic issue anyway so it's all for good.
I haven't written the extension guide documentation yet but let's agree on this first.
One thing that is a bit less nice compared to the handcrafted output is that we lost the nice titled sections but I think having everything generated is worth it.
At some point, we could imagine a new tag to generate proper sections but let's do that another day.
Once Asciidoclet has the related patch, we will have a proper output in the generated Javadoc too.
@machi1990 could you upgrade your repository with this PR and point to it so that Emmanuel can have a look?
Note that GitHub does not support the new Font Awesome icons, I will attach a few screenshots.
Summary table
Details with Asciidoc