diff --git a/README.md b/README.md index 47d4b35..906cabd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ -# jakartaee-documentation +# Jakarta EE Documentation -This is the repo for building the Jakarta EE Documentation site (from different repos); currently this consists of the Jakarta EE Tutorial. +This is the repo for building the Jakarta EE Documentation site (from different repos); currently this consists of the Jakarta EE Tutorial and Eclipse Cargo Tracker. - Repo for the tutorial content: [https://github.com/jakartaee/jakartaee-tutorial/](https://github.com/jakartaee/jakartaee-tutorial/) +- Repo for the Cargo Tracker content (note that the content resides in the docs branch): [https://github.com/eclipse-ee4j/cargotracker/tree/docs](https://github.com/eclipse-ee4j/cargotracker/tree/docs) - Repo for the documentation UI: [https://github.com/jakartaee/jakartaee-documentation-ui/](https://github.com/jakartaee/jakartaee-documentation-ui/) ## Prerequisites @@ -15,7 +16,7 @@ This is the repo for building the Jakarta EE Documentation site (from different JDK and Maven speak for themselves. -Ruby, if `ruby -v` returns something like `Command 'ruby' not found` then [read the instructions](https://rvm.io/rvm/install) to install "RVM stable". +For Ruby, if `ruby -v` returns something like `Command 'ruby' not found` then [read the instructions](https://rvm.io/rvm/install) to install "RVM stable". Summarized: ```bash @@ -24,7 +25,7 @@ curl -sSL https://get.rvm.io | bash -s stable --ruby source ~/.rvm/scripts/rvm ``` -And finally install the [`asciidoctor-pdf`](https://rubygems.org/gems/asciidoctor-pdf) gem: +Finally, you will also need to install the [`asciidoctor-pdf`](https://rubygems.org/gems/asciidoctor-pdf) gem: ```bash gem install asciidoctor-pdf @@ -39,23 +40,29 @@ mvn clean package ``` The output will be in `target/generated-docs`. -To view, just open [`target/generated-docs/jakartaee-tutorial/current/index.html`](target/generated-docs/jakartaee-tutorial/current/index.html) in a browser. +To view the Tutorial, open [`target/generated-docs/jakartaee-tutorial/current/index.html`](target/generated-docs/jakartaee-tutorial/current/index.html) in a browser. ```bash browse target/generated-docs/jakartaee-tutorial/current/index.html ``` +To view Cargo Tracker, open [`target/generated-docs/cargotracker-documentation/current/index.html`](target/generated-docs/cargotracker-documentation/current/index.html) in a browser. + +```bash +browse target/generated-docs/cargotracker-documentation/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: +Then you need to run this command beforehand: ```bash source ~/.rvm/scripts/rvm ``` -Or to make sure this is executed every time you open a new terminal. +You will need to make sure this is executed every time you open a new terminal. You could also simply add the script to your login profile. ### Author Mode @@ -87,7 +94,28 @@ Summarized: branches: - yourBranchName ``` -3. In case you wish to use a different `jakartaee-documentation-ui` bundle, edit the `ui` entry. +3. In case you wish to use a different `cargotracker` branch, edit the `content` entry. + * In case you wish to use the current local repo and branch: + ``` + content: + sources: + - url: ../cargotracker + start_paths: + - src/main/antora + branches: + - docs + ``` + * In case you wish to use a different remote branch, e.g. when you have forked the `cargotracker` repo: + ``` + content: + sources: + - url: https://github.com/yourGitUserName/cargotracker.git + start_paths: + - src/main/antora + branches: + - yourBranchName + ``` +4. 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: @@ -118,6 +146,10 @@ The output will still be in the same location, but it'll be generated from your browse target/generated-docs/jakartaee-tutorial/current/index.html ``` +```bash +browse target/generated-docs/cargotracker-documentation/current/index.html +``` + ## Deploying This site is currently deployed via GitHub Pages via GitHub Actions.