ARTEMIS-6111 migrate doc build to Antora#6506
Conversation
|
Looks good! Improved navigation and added (or returned) searchability is great! |
| </groupOrder> | ||
| <header>= Artemis JMS Client Dependencies | ||
| // generated content! | ||
| <dependencies> |
There was a problem hiding this comment.
The dependencies (and build / plugins) were in the release profile so that they dont get pulled at all except if building the docs. This includes should anyone decide to grab the resulting jar file with the output docs, which would now pull the client+broker.
There was a problem hiding this comment.
Fixed.
To be clear, I removed the apache-release-docs-playbook.xml completely as it makes more sense to have that in the artemis-website project.
| <properties> | ||
| <skipWebsiteDocGeneration>false</skipWebsiteDocGeneration> | ||
| <skipWebsiteJavadocGeneration>false</skipWebsiteJavadocGeneration> | ||
| <antora.playbook>apache-release-docs-playbook.yml</antora.playbook> |
There was a problem hiding this comment.
I think we can just put the main bits back into the release profile, and if wanting to use this profile to run different config then just have it with only this single antora.playbook property set by this profile to adjust the config. Both profiles are set during the release build.
Alternatively, perhaps we make this modules build purely local-only for the current sources for development purposes, not deploy anything at all from it, and have the 'website version output' config+build in the website repo instead, where it can decide what versions are used etc. Or was that the thinking, since I notice the file doesnt specify any versions etc (since no tag obviously exists yet), and updating it for each release seems like it could be a pain. Is it meant as a template?
We might need to consider the precise setup for others reasons too, such as reproducibility. I also notice that using the 'docs-playbook.yml' file (just release profile) results in content that embeds the branch name (presumably tag instead if thats what checked out?), e.g. I saw this this in the local -Prelease build I just did after pulling your changes:
<link rel="canonical" href="https://artemis.apache.org/user-manual/jbertram-ARTEMIS-6111/index.html">
I guess similar links would appear in a run with specified versions in apache-release-docs-playbook.yml, so the URL would need to match what the site does. It would probably be good to have a matching set up updates for the site repo before merging (could e.g run against a forks tag of these changes for development)
There was a problem hiding this comment.
I agree with making this purely local and moving the website output to the artemis-website repo.
| @@ -0,0 +1,6 @@ | |||
| name: migration-guide | |||
There was a problem hiding this comment.
Rather than integrating this I'd be thinking instead about removing it.
Its not updated. Tooling it references is not maintained. Its a different project now. Although a copy is on the site, the site does not link to it at all (the dir is mentioned once in the hacking-guide) so its only available by redirect from old links. The version on the site was published with gitbook, which we havent used for several years (is this the third docs build change since then?).
|
no more PDF? |
|
It's a lot better than the current HTML. very nice. But I liked the PDF particularly. It would be nice to keep the PDF unless it's extremely difficult to do it. |
|
just read your point on the PDF... although the reason I liked the PDF was searchability... If the HML is good enough we probably don't need it. |
4 participants
See the Jira for a list of the benefits of this migration.
The two down-sides of this so far:
-all.jaralternatives.Give this a try by executing the following in
artemis-website:Output will be in
target/site.Here's a preview:
Here's that same shot of the old docs:
Assuming the consensus is positive I will still need to update
RELEASING.adoc.