Skip to content

Latest commit

 

History

History
126 lines (95 loc) · 4.5 KB

README.md

File metadata and controls

126 lines (95 loc) · 4.5 KB
Raw

jakartaee-documentation

This is the repo for building the Jakarta EE Documentation site (from different repos); currently this consists of the Jakarta EE Tutorial.

Prerequisites

Setup

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

Building

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.

Author Mode

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:

  1. Copy and paste antora-playbook.yml in same folder as local-antora-playbook.yml.
  2. In case you wish to use a different jakartaee-tutorial branch, edit the content 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
  3. In case you wish to use a different jakartaee-documentation-ui bundle, edit the ui 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: 
      ui:
  output_dir: _
  bundle:
    url: ../jakartaee-documentation-ui/build/ui-bundle.zip
    snapshot: true
      Note that this assumes that you have the UI repo checked out in the same parent folder as the current repo.
    • 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

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

Deploying

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/.