You’re currently viewing the Antora playbook branch. The playbook branch hosts the docs build that is used to build and publish the production docs site.

The Spring Cli reference docs are built using Antora. This README covers how to build the docs in a software branch as well as how to build the production docs site locally.

To prepare your system for building the documentation, install the prerequisites and then create your workspace and build the main branch documentation. Once you’ve completed those steps, follow the instructions in Build the 6.0.x branch documentation to learn how to build the documentation for a version branch you haven’t previously checked out.

To build the production site documentation on your computer, follow the instructions in Prerequisites, Build the main branch documentation, and then Build the production documentation site.

These instructions assume you already have basic tools on your system, including bash, zip, unzip, git, and curl. In addition to these basic tools, you need SDKMAN! installed so that the correct JDK is set for each branch.

1. Open your terminal and enter the following command:

   $ curl -s "https://get.sdkman.io" | bash

   This command downloads and installs SDKMAN! Once installation is complete, you should see a command displayed in your terminal that will initiate SDKMAN.

2. Copy the command displayed in your terminal and run it. $HOME is the path unique to your computer (e.g., home/my-jam/.sdkman/bin/sdkman-init.sh).

   $ source "$HOME/.sdkman/bin/sdkman-init.sh"

You’ll use SDKMAN in the next sections to install and switch to the JDK required for each branch. Now you’re ready to create your workspace.

Your workspace will be the folder that contains the git worktrees of the project.

1. In your terminal, create a directory for the project and then change into that directory.

   $ mkdir spring-cli
   $ cd spring-cli

2. Clone the project repository and create the primary worktree for the main branch. Then change into the new main folder.

   $ git clone https://github.com/spring-projects/spring-cli main
   $ cd main

3. Switch to the required JDK using SDKMAN by running the following command:

   $ sdk env || sdk env install

   SDKMAN will switch to the required JDK or install it if it isn’t present.

4. Generate the documentation with Antora using the following command:

   $ ./gradlew antora

   This command will build the documentation, including any generated attributes, for the main branch.

5. Navigate to $HOME/spring-cli/main/docs/build/site/spring-cli/index.html to view the generated documentation.

To build the project’s production site, you’ll set up a worktree for the docs-build branch of the repository.

1. To add a worktree, you have to be in a worktree. In your terminal, change to the main folder if you aren’t already in it, e.g., $HOME/spring-cli/main. Run the following command to set up the worktree for the docs-build branch. Then change into the new docs-build directory.

   $ git worktree add ../docs-build docs-build --track
   $ cd ../docs-build

2. Switch to the required JDK or install it.

   $ sdk env || sdk env install

3. Generate the documentation for the project’s production site using the following command:

   $ ./gradlew antora

   This command will build all of the documentation included in the project’s production site from the repository on GitHub.

   To build the documentation from the current clone, using any worktrees that are available, use the following command instead:

   $ ./gradlew antora

4. Navigate to $HOME/spring-cli/docs-build/build/site/spring-cli/index.html to view the generated documentation.