Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Config Doc - Support more features in Asciidoc -> Mardown converter #43287

Open
gsmet opened this issue Sep 13, 2024 · 4 comments
Open

Config Doc - Support more features in Asciidoc -> Mardown converter #43287

gsmet opened this issue Sep 13, 2024 · 4 comments
Labels

Comments

@gsmet
Copy link
Member

gsmet commented Sep 13, 2024

While I implemented a first version of an AsciiDoc -> Markdown converter here: #42677 (see specific commit introducing the asciidocToMarkdown method in JavadocToMarkdownTransformer), there are still features that we need to support...

A good example of what we need is in the https://quarkus.io/guides/hibernate-search-orm-elasticsearch#configuration-reference-main where Yoann had a lot of fun.

  • Ideally, we would need to support some of the Asciidoc attributes such as {hibernate-search-docs-url}. They would have to be obtained from the Maven properties as they are currently defined there and we want to be consistent.
  • We would have to support the dt/dd constructs:
`simple`::
The default, future-proof strategy: if the index name in Hibernate Search is `myIndex`,
this strategy will create an index named `myindex-000001`, an alias for write operations named `myindex-write`,
and an alias for read operations named `myindex-read`.
`no-alias`::
A strategy without index aliases, mostly useful on legacy clusters:
if the index name in Hibernate Search is `myIndex`,
this strategy will create an index named `myindex`, and will not use any alias.
  • We would have to support tables (note that they are not using the usual | marker so we would have to support whatever is there):
[cols=5]
!===
.2+h!Strategy
.2+h!Throughput
3+^h!Guarantees when the application thread resumes

h!Changes applied
h!Changes safe from crash/power loss
h!Changes visible on search

!async
!Best
^!icon:times[role=red]
^!icon:times[role=red]
^!icon:times[role=red]

!write-sync (**default**)
!Medium
^!icon:check[role=lime]
^!icon:check[role=lime]
^!icon:times[role=red]

!read-sync
!Medium to worst
^!icon:check[role=lime]
^!icon:times[role=red]
^!icon:check[role=lime]

!sync
!Worst
^!icon:check[role=lime]
^!icon:check[role=lime]
^!icon:check[role=lime]
!===

Given the complexity of these tables, we won't be able to render them as plain Markdown tables so they will have to be rendered as HTML. We might not be able to render all the subtleties in Markdown (typically not sure if we can center things when using HTML in Markdow...).
It should be rendered as:
Screenshot from 2024-09-13 19-40-01

  • And given what I just pasted, we would have to translate some of the icons too.

And probably more to follow...

@quarkus-bot
Copy link

quarkus-bot bot commented Sep 13, 2024

/cc @radcortez (config)

@gsmet gsmet added the good first issue Good for newcomers label Sep 13, 2024
@gsmet
Copy link
Member Author

gsmet commented Sep 13, 2024

FWIW, I think it might be a good first issue as it's really tied to the core/processor module and might be easier with some AI help.

@gsmet
Copy link
Member Author

gsmet commented Sep 13, 2024

@ppalaga it would be helpful if you could have a look at what I did here: 10ffdcb and add more things that we need to support.

@ppalaga
Copy link
Contributor

ppalaga commented Sep 16, 2024

Thanks for the heads up, @gsmet. I wonder whether you have any good method to validate the output for a given extension? My understanding is that it is supposed to output some structured output for IDEs. Are there some (which) IDEs supporting that format already? Do I need some specific IDE plugin to view the rendered config property docs?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Development

No branches or pull requests

2 participants