Merge pull request #29 from m-reza-rahman/main

Include Cargo Tracker

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.