Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a new section to the README that explains how to add a new content repo #36

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add a new section to the README that explains how to add a new content repo #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 177 additions & 73 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ currently this consists of the Jakarta EE Tutorial and Eclipse Cargo Tracker.

- [https://github.com/jakartaee/jakartaee-tutorial/](https://github.com/jakartaee/jakartaee-tutorial/) - Jakarta EE Tutorial content
- [https://github.com/eclipse-ee4j/cargotracker/tree/docs](https://github.com/eclipse-ee4j/cargotracker/tree/docs) - Cargo Tracker content (note that the content resides in the `docs` branch)
- [https://github.com/jakartaee/jakartaee-documentation-ui/](https://github.com/jakartaee/jakartaee-documentation-ui/) - HTML and CSS assets used for the documentation site look and feel
- [https://github.com/jakartaee/jakartaee-documentation-ui/](https://github.com/jakartaee/jakartaee-documentation-ui/) - HTML and CSS assets used for the documentation site look and feel

## Prerequisites

The tools below are all required for building this project.
The tools below are all required for building this project.

Maven drives the entire process, requires the Java Development Kit (JDK).
[Asciidoctor](https://asciidoctor.org/), which processes the documentation content, requires Ruby.
Expand All @@ -22,22 +22,22 @@ but Maven automatically handles installation and execution.
- [Maven](https://maven.apache.org/)
- [Ruby](https://rvm.io/)

> NOTE: We assume you're using a UNIX/Linux shell such as bash, zsh, or sh.
On Windows, we assume you're using Git Bash or Windows Subsystem for Linux. If not, you'll have to translate these commands to PowerShell or Command Prompt commands.
> NOTE: We assume you're using a UNIX/Linux shell such as bash, zsh, or sh.
> On Windows, we assume you're using Git Bash or Windows Subsystem for Linux. If not, you'll have to translate these commands to PowerShell or Command Prompt commands.

## Setup

### JDK

Any recent JDK will do.
If you don't have a Java installed, you can get a recent version here: https://jdk.java.net/.
If you want to manage multiple JDKs on your system,
Any recent JDK will do.
If you don't have a Java installed, you can get a recent version here: https://jdk.java.net/.
If you want to manage multiple JDKs on your system,
consider using [SDKMan](https://sdkman.io/) or [jenv](https://www.jenv.be/).

### Maven

Any recent version of Maven will do.
If you don't have it installed, [download Maven](https://maven.apache.org/download.cgi)
If you don't have it installed, [download Maven](https://maven.apache.org/download.cgi)
and then install it manually by following [these directions](https://maven.apache.org/install.html).

### Ruby
Expand Down Expand Up @@ -84,33 +84,39 @@ The output will be in `target/generated-docs`.
To view the Tutorial, open [`target/generated-docs/jakartaee-tutorial/current/index.html`](target/generated-docs/jakartaee-tutorial/current/index.html) in a browser.

Linux

```bash
browse target/generated-docs/jakartaee-tutorial/current/index.html
```

macOS

```bash
open target/generated-docs/jakartaee-tutorial/current/index.html
```

Windows

```bash
start 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.

Linux

```bash
browse target/generated-docs/cargotracker-documentation/current/index.html
```

macOS

```bash
open target/generated-docs/cargotracker-documentation/current/index.html
```

Windows

```bash
start target/generated-docs/cargotracker-documentation/current/index.html
```
Expand All @@ -121,83 +127,83 @@ Antora supports an Author Mode that lets you work with local branches and your l
This requires that you keep a local copy of `antora-playbook.yml` as `local-antora-playbook.yml`.

We recommend cloning other repos which have content you want to modify.
For example, let's say you want to modify content in the
[jakartaee-tutorial](https://github.com/jakartaee/jakartaee-tutorial/) and
For example, let's say you want to modify content in the
[jakartaee-tutorial](https://github.com/jakartaee/jakartaee-tutorial/) and
[cargotracker](https://github.com/eclipse-ee4j/cargotracker/tree/docs) repos.

You'd clone the repos in the same parent folder as this repo, so you'd end up with this directory structure:

```bash
├── parent-directory
├── jakartaee-documentation/
└── jakartaee-tutorial/
└── cargotracker/
```
```bash
├── parent-directory
├── jakartaee-documentation/
└── jakartaee-tutorial/
└── cargotracker/
```

You can [Use Author Mode :: Antora Docs](https://docs.antora.org/antora/latest/playbook/author-mode/) for details,
but here is the summary of the process:

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 `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
```
- 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:
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:

Expand All @@ -209,6 +215,104 @@ The output will still be in the same location, but it'll be generated from your

You can then view it as described in the [Viewing Output](#viewing-output) section above.

## Adding a New Documentation Component to the Jakarta EE Documentation Site

This guide explains how to integrate a new documentation component
into the Jakarta EE Documentation site using Antora. Following these
steps will allow you to add any documentation site as a component,
making it accessible from the main Jakarta EE documentation portal.

### Prerequisites

- Familiarity with Antora, the tool managing documentation
components for the Jakarta EE site.
- Access to the repositories for both Jakarta EE documentation and
the new documentation component to configure branches and make
necessary changes.

### Steps to Add a New Documentation Component

1. Set Up the Documentation Source in the New Component Repository:

- In the repository of the new documentation component, create a branch (e.g., docs) that will store the documentation source files.
- Organize documentation content in a directory, typically `src/main/antora`, containing the necessary Antora files (`antora.yml` and any `.adoc` files).
- Configure the `antora.yml` file with the component name, version, and any additional metadata relevant to the component.

2. Configure the Jakarta EE Documentation Playbook:

- The Jakarta EE documentation site is managed by an Antora playbook
file, such as `antora-playbook.yml`. In this file, add the new
documentation component as a content source under the `content.sources` section.

- Add the following configuration, replacing`<repository-url>`,
`<directory-path>`, and `<branch-name>` with values specific to
the new component:

content:
sources:
- url: <repository-url>
start_paths:
- <directory-path>
branches:
- <branch-name>

- This setup directs Antora to retrieve documentation content from the specified repository branch and directory path.

3. Check Site Information:

- In the `site` section of the playbook, verify the Jakarta EE
Documentation’s main URL, title, and start page configurations:

site:
url: https://jakarta.ee/learn/docs/
title: Jakarta EE Documentation
start_page: jakartaee-tutorial:ROOT:index.adoc
keys:
googleAnalytics: GTM-5WLCZXC

4. Test the New Component Locally:

- Build the documentation site locally to ensure the new component
integrates correctly:

antora antora-playbook.yml

- Verify that the new component’s content appears as expected, with correct links, structure, and layout.

5. Deploy the Updated Site:

- Once verified, commit and push the changes to the main branch
of the Jakarta EE documentation repository in a pull request,
triggering the GitHub Actions workflow for redeployment.

- After deployment, check the live site at Jakarta EE
Documentation to confirm that the new component is accessible
and correctly integrated.

6. Ongoing Maintenance:

- Update the branch of the new component’s repository as
documentation evolves. The Jakarta EE documentation site will
need to be rebuilt and redeployed to incorporate these updates.

### Example Configuration

Here is an example of how the content.sources section might look
when adding multiple documentation components:

content:
sources:
- url: https://github.com/jakartaee/jakartaee-tutorial.git
start_paths:
- src/main/antora
branches:
- main
- url: https://github.com/<new-component-repo>.git
start_paths:
- <new-directory-path>
branches:
- <new-branch-name>

## Deploying

This site is currently deployed via GitHub Pages via GitHub Actions.
Expand Down
Loading