Skip to content

Conversation

marko-bekhta
Copy link
Member

@marko-bekhta marko-bekhta commented Oct 1, 2025

https://hibernate.atlassian.net/browse/HHH-19827

There are a few things here 🙂

  • code highlighter doesn't like the lang to be uppercased, and won't highlight if it is
  • adding Asciidoctor extensions only works with service loader in Gradle, hence there's a new "local" project local-build-asciidoctor-extensions that creates the required ExtensionRegistry
  • some of the adoc files are renamed to index.adoc so that we render the index.html and do not have the duplicate path parts in the urls (TODO: have redirects)
  • executionMode = ExecutionMode.JAVA_EXEC on Asciidoctor tasks seems to help with memory issues (at least locally for me 😃)
  • I removed some of the ../.. paths from the attributes and instead pass some "root" dirs from the gradle config to be used in the adoc files.
  • pdf files kept their original names (there's an extra doLast to rename the index.pdf to whatever the name was.
  • oh and yeah a common theme is applied to all rendered docs 😃

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license
and can be relicensed under the terms of the LGPL v2.1 license in the future at the maintainers' discretion.
For more information on licensing, please check here.


@mbellade
Copy link
Member

mbellade commented Oct 2, 2025

  • some of the adoc files are renamed to index.adoc so that we render the index.html and do not have the duplicate path parts in the urls (TODO: have redirects)

Not sure that's a good idea, unless we will have redirections setup before merging this PR. I would imagine there will be plenty of links to specific docs all over the place that would be broken by this, I myself have several bookmarks that would stop working.

executionMode = ExecutionMode.JAVA_EXEC on Asciidoctor tasks seems to help with memory issues (at least locally for me 😃)

Does this mean that documentation is being rendered more slowly (not concurrently) now? I guess that is fine if it prevents potential failures, but I thought the build was working fine on CI, and the task documentation says:

If you run a lot of builds the penalty start-up time might become an issue for you.

Which we kind of do - perhaps we could make this configurable?

@marko-bekhta
Copy link
Member Author

will have redirections

yeah, that's the idea. Otherwise, it would be only ORM having this https://docs.jboss.org/hibernate/orm/7.1/whats-new/whats-new.html repeated path element structure ...

ExecutionMode.JAVA_EXEC
I've tried running locally with it:

BUILD SUCCESSFUL in 1m 52s

and without:

BUILD SUCCESSFUL in 1m 53s

^this includes building the javadocs and reports and then rendering the htmls/pdfs

so it doesn't seem like there's much difference, but if we see the builds are slower with it then we can make it conditional ?

:toc2:
:toclevels: 3
:sectanchors:
:version-selector-enabled: true
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a nice features, perhaps we should also have it on other docs? Migration guide and what's new seems like the obvious candidates, perhaps even the introduction guide (though that didn't exist in earlier versions, I wonder what happens then).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 it would be nice to have it 🙂 . Though we'll have to figure out a better way to create links for the versions...
Right now, the way that selector works is that it just tries to replace the version in the path, so for these other guides, we may end up with a lot of 404 😖

but Yoann has this idea: hibernate/hibernate.org#285 maybe with that we can do better on the other docs 🤞🏻

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, if we already need a script to determine versions might as well feed it the correct information

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

Successfully merging this pull request may close these issues.

2 participants