-
-
Notifications
You must be signed in to change notification settings - Fork 3.7k
HHH-19827 Apply the unified Hibernate Documentation theme #11049
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
base: main
Are you sure you want to change the base?
Conversation
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.
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:
Which we kind of do - perhaps we could make this configurable? |
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 ...
and without:
^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 |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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 🤞🏻
There was a problem hiding this comment.
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
- do not pull rouge gem as it comes bundled with AsciidoctorJ distribution - override AsciidoctorJ version - bump pdf dependency version to the latest
…d duplicated references
to help prevent the OOMs that usually occur locally, especially when building PDFs
since rouge can only handle a lowercased languages ....
685e281
to
d3398e5
Compare
https://hibernate.atlassian.net/browse/HHH-19827
There are a few things here 🙂
local-build-asciidoctor-extensions
that creates the requiredExtensionRegistry
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 😃)../..
paths from the attributes and instead pass some "root" dirs from the gradle config to be used in the adoc files.doLast
to rename the index.pdf to whatever the name was.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.