Create a script to build jakartaee docs locally

README.md

@@ -61,50 +61,50 @@ 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](https://docs.antora.org/antora/latest/playbook/author-mode/) for details. 
+Read [Use Author Mode :: Antora Docs](https://docs.antora.org/antora/latest/playbook/author-mode/) 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
-        ```
+   - 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
-        ```
+   - 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:
 
@@ -118,6 +118,93 @@ 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
 ```
 
+### Run and Build Jakarta EE Documentation in Author Mode Using `build-jakartaee-docs.sh` Script
+
+This documentation describes how to use `build-jakartaee-docs.sh`
+script to automate the process of building the Jakarta EE
+Documentation UI and Jakarta EE Documentation repositories in author
+mode.
+This script simplifies the workflow by handling UI bundle creation,
+playbook configuration, and documentation building, while ensuring
+platform compatibility (Linux,
+macOS, and Windows).
+
+### Prerequisites
+
+Before using the script, ensure that:
+
+- You have cloned both repositories `jakartaee-documentation-ui` and `jakartaee-documentation` in the same parent directory:
+
+  ```bash
+  ├── parent-directory
+      ├── jakartaee-documentation-ui/
+      └── jakartaee-documentation/
+  ```
+
+- Node.js and Gulp are installed for building the UI.
+- Apache Maven is installed for building the documentation.
+- You are running the script from the root of the `jakartaee-documentation` repository.
+
+### Using the Script
+
+1. The `build-jakartaee-docs.sh` script is in the root directory of
+   `jakartaee-documentation`.
+
+2. Ensure both `jakartaee-documentation-ui` and
+   `jakartaee-documentation` repositories are cloned in the same parent
+   directory.
+
+3. Make the script executable by running.
+
+   ```bash
+   chmod +x build-jakartaee-docs.sh
+   ```
+
+4. Run the script from the terminal or command line:
+
+   ```bash
+   ./build-and-run.sh
+   ```
+
+5. The script will automatically:
+   - Build the Jakarta EE Documentation UI.
+   - Copy and modify the playbook.
+   - Build the Jakarta EE Documentation in author mode.
+   - Open the resulting index.html in your default browser.
+
+### Script Overview
+
+The script performs the following steps:
+
+1. Build `jakartaee-documentation-ui:`
+
+   - Navigates to the `jakartaee-documentation-ui` repository and builds the UI using gulp bundle.
+
+2. Switch Back to `jakartaee-documentation:`
+
+   - Navigates back to the `jakartaee-documentation` repository after building the UI.
+
+3. Copy the Antora Playbook:
+
+   - Copies the existing `antora-playbook.yml` to a new file called `local-antora-playbook.yml` to be used for the local setup.
+
+4. Modify `local-antora-playbook.yml:`
+
+   - Updates the `ui.bundle.url` in the playbook to point to the locally
+     built UI bundle located at `../jakartaee-documentation-ui/build/
+ui-bundle.zip` instead of the remote prebuilt bundle.
+
+5. Build the Jakarta EE Documentation:
+
+   - Builds the documentation in author mode by running the command
+     `mvn compile -Pauthor-mode`.
+
+6. Open the Generated `index.html`:
+   - After the Maven build completes, the script navigates to the
+     `target/generated-docs` directory and opens the `index.html` file
+     in the default web browser. The script supports opening the file
+     on Linux, macOS, and Windows.
+
 ## Deploying
 
 This site is currently deployed via GitHub Pages via GitHub Actions.

build-jakartaee-docs.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+# Step 1: Navigate to the jakartaee-documentation-ui repository and build it
+echo "Navigating to jakartaee-documentation-ui and building..."
+cd ../jakartaee-documentation-ui || { echo "Error: jakartaee-documentation-ui directory not found."; exit 1; }
+gulp bundle
+if [ $? -ne 0 ]; then
+  echo "Error: Failed to build jakartaee-documentation-ui."
+  exit 1
+fi
+echo "Successfully built jakartaee-documentation-ui."
+
+# Step 2: Navigate back to jakartaee-documentation
+cd ../jakartaee-documentation || { echo "Error: Failed to return to jakartaee-documentation directory."; exit 1; }
+echo "Returned to jakartaee-documentation directory."
+
+# Step 3: Create a local-antora-playbook.yml by copying the existing antora-playbook.yml
+echo "Creating local-antora-playbook.yml..."
+cp antora-playbook.yml local-antora-playbook.yml
+if [ $? -ne 0 ]; then
+  echo "Error: Failed to create local-antora-playbook.yml."
+  exit 1
+fi
+echo "Successfully created local-antora-playbook.yml."
+
+# Step 4: Update the ui.bundle.url in local-antora-playbook.yml
+echo "Updating ui.bundle.url in local-antora-playbook.yml..."
+sed -i '' "s|url: https://github.com/jakartaee/jakartaee-documentation-ui/releases/download/latest/ui-bundle.zip|url: ../jakartaee-documentation-ui/build/ui-bundle.zip|g" local-antora-playbook.yml
+if [ $? -ne 0 ]; then
+  echo "Error: Failed to update ui.bundle.url."
+  exit 1
+fi
+echo "Successfully updated ui.bundle.url to use the local UI bundle."
+
+# Step 5: Build jakartaee-documentation
+echo "Building jakartaee-documentation..."
+mvn compile -Pauthor-mode
+if [ $? -ne 0 ]; then
+  echo "Error: Failed to build jakartaee-documentation."
+  exit 1
+fi
+echo "Successfully built jakartaee-documentation."
+
+# Step 6: Open index.html from target/generated-docs based on the OS
+echo "Opening index.html from target/generated-docs..."
+cd target/generated-docs || { echo "Error: target/generated-docs directory not found."; exit 1; }
+
+# Detect the operating system and open the file accordingly
+case "$OSTYPE" in
+  darwin*)  open index.html ;;             # macOS
+  linux*)   xdg-open index.html ;;         # Linux
+  msys*|cygwin*) start index.html ;;       # Windows (using Git Bash or Cygwin)
+  *)        echo "Unsupported OS: $OSTYPE. Cannot open index.html automatically." ;;
+esac
+
+if [ $? -ne 0 ]; then
+  echo "Error: Failed to open index.html."
+  exit 1
+fi
+echo "index.html opened successfully."
+
+# End of script