spring-security/README.adoc

= Spring Security Docs Build

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 Security reference docs are built using https://antora.org[Antora].
This README covers how to build the docs in a software branch as well as how to build the production docs site locally.

== Overview

To prepare your system for building the documentation, <<prerequisites,install the prerequisites>> and then <<build-main,create your workspace and build the main branch documentation>>.
Once you've completed those steps, follow the instructions in <<build-branch,Build the 5.8.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,Prerequisites>>, <<build-main,Build the main branch documentation>>, and then <<build-production,Build the production documentation site>>.

.Branch checkout instead of worktrees
[NOTE]
====
If you prefer to set up your workspace without worktrees, complete the steps in <<prerequisites,Prerequisites>> and clone the project repository onto your computer.
Then follow the instructions in each section starting from the `sdk env || sdk env install` step once you've checked out the desired branch.
====

[#prerequisites]
== Prerequisites (everyone)

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 https://sdkman.io/install[SDKMAN!] installed so that the correct JDK is set for each branch.

. 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.
--

. 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 <<build-main,create your workspace>>.

[#build-main]
== Build the main branch documentation (writers)

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

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

 $ mkdir spring-security
 $ cd spring-security

. 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-security main
 $ cd main

. 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.
--

. Generate the documentation with Antora using the following command:
+
--
 $ ./gradlew -PbuildSrc.skipTests=true :spring-security-docs:antora

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

. Navigate to _$HOME/spring-security/main/docs/build/site/index.html_ to view the generated documentation.

[#build-branch]
== Build the 5.8.x branch documentation (writers)

NOTE: The instructions in this section assume you've completed the steps in the <<build-main,previous section>>.

After creating the worktree for the main branch, you can set up a worktree for any other branches you'll work on in the future.
In this section, you'll create a worktree for the 5.8.x branch in your project workspace.

. 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-security/main_.
Set up a worktree for the 5.8.x branch and then change into the new directory by running the following commands:

 $ git worktree add ../5.8.x 5.8.x --track
 $ cd ../5.8.x

. Switch to the required JDK or install it.

 $ sdk env || sdk env install

. Generate the documentation with the following command:
+
--
 $ ./gradlew -PbuildSrc.skipTests=true :spring-security-docs:antora

This command will build the documentation, including any generated attributes, for the 5.8.x branch.
--

. Navigate to _$HOME/spring-security/5.8.x/docs/build/site/index.html_ to view the generated documentation.

[#build-production]
== Build the production documentation site (docs manager)

NOTE: The instructions in this section assume you've <<build-main,prepared your workspace and created the worktree for the main branch>>.

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

. 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-security/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

. Switch to the required JDK or install it.

 $ sdk env || sdk env install

. 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 --playbook local-antora-playbook.yml
--

. Navigate to _$HOME/spring-security/docs-site/build/site/index.html_ to view the generated documentation.

[#trigger]
== Trigger the documentation build workflow (docs manager)

You can either trigger the production document build using the Deploy Docs entry in the GitHub Actions web UI or using the https://cli.github.com/[GitHub CLI].

=== GitHub Actions web UI

In the GitHub Actions web UI, click the Deploy Docs entry.
Click on the "Run workflow" menu.
Select the branch `docs-build` and click "Run workflow" to trigger a full build.
To trigger a partial build, specify a release line branch name in the input field labeled "Enter git refname to build".

=== GitHub CLI

Starting from within the cloned repository (ideally the playbook branch), here's how to trigger a full build of the documentation site using the `gh` command:

 $ gh workflow run deploy-docs.yml --ref docs-build

Here's how to trigger a partial build of a single version (based on the release line branch name):

 $ gh workflow run deploy-docs.yml --ref docs-build -f build-refname=5.7.x

Run `gh help workflow run` to show the docs for this command and other examples of how to use it.

If you're not running the `gh` command from within the cloned repository, you can specify the repository using the `--repo` CLI option (e.g., `--repo spring-projects/spring-security`).