This is the repo for building the Jakarta EE Documentation site (from different repos); currently this consists of the Jakarta EE Tutorial.
- Repo for the tutorial content: https://github.com/jakartaee/jakartaee-tutorial/
- Repo for the documentation UI: https://github.com/jakartaee/jakartaee-documentation-ui/
JDK and Maven speak for themselves.
Ruby, if ruby -v
returns something like Command 'ruby' not found
then read the instructions to install "RVM stable".
Summarized:
gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable --ruby
source ~/.rvm/scripts/rvm
And finally install the asciidoctor-pdf
gem:
gem install asciidoctor-pdf
To build, run:
mvn clean package
The output will be in target/generated-docs
.
To view, just open target/generated-docs/jakartaee-tutorial/current/index.html
in a browser.
browse target/generated-docs/jakartaee-tutorial/current/index.html
If you face a build failure with the following log entry as the last one before the failure, basically saying "Command not found: asciidoctor-pdf":
[INFO] {"level":"fatal","time":1684333903235,"name":"antora","hint":"Add the --stacktrace option to see the cause of the error.","msg":"Command not found: asciidoctor-pdf"}
Then you need to run beforehand:
source ~/.rvm/scripts/rvm
Or to make sure this is executed every time you open a new terminal.
Antora supports an Author Mode that lets you work with local branches and your local worktree.
This requires that you keep a local copy of antora-playbook.yml
as local-antora-playbook.yml
.
Read Use Author Mode :: Antora Docs for details.
Summarized:
- Copy and paste
antora-playbook.yml
in same folder aslocal-antora-playbook.yml
. - In case you wish to use a different
jakartaee-tutorial
branch, edit thecontent
entry.- In case you wish to use the current local repo and branch:
content: sources: - url: ../jakartaee-tutorial start_paths: - src/main/antora branches: - HEAD
- In case you wish to use a different remote branch, e.g. when you have forked the
jakartaee-tutorial
repo:content: sources: - url: https://github.com/yourGitUserName/jakartaee-tutorial.git start_paths: - src/main/antora branches: - yourBranchName
- In case you wish to use the current local repo and branch:
- In case you wish to use a different
jakartaee-documentation-ui
bundle, edit theui
entry.- In case you wish to use the locally built
jakartaee-documentation-ui
bundle as instructed in "Package the UI" section of the README over there:Note that this assumes that you have the UI repo checked out in the same parent folder as the current repo.ui: output_dir: _ bundle: url: ../jakartaee-documentation-ui/build/ui-bundle.zip snapshot: true
- In case you wish to use a different release, e.g. when you have forked the
jakartaee-documentation-ui
repo:ui: output_dir: _ bundle: url: https://github.com/yourGitUserName/jakartaee-documentation-ui/releases/download/latest/ui-bundle.zip snapshot: true
- In case you wish to use the locally built
Once you've created the local-antora-playbook.yml
file, you can use the author-mode
Maven profile:
mvn compile -Pauthor-mode
The output will still be in the same location, but it'll be generated from your local clone of the repos instead of the remote.
browse target/generated-docs/jakartaee-tutorial/current/index.html
This site is currently deployed via GitHub Pages via GitHub Actions. For details, see the workflow file.
The current URL is https://jakartaee.github.io/jakartaee-documentation/.