Migrate docs to Antora

Issue gh-1295

Author: rwinch

.gitignore

@@ -37,3 +37,4 @@ out/
 
 ### Mac ###
 .DS_Store
+cached-antora-playbook.yml

docs/.github/workflows/deploy-docs.yml

@@ -0,0 +1,33 @@
+name: Deploy Docs
+on:
+  push:
+    branches-ignore: [ gh-pages ]
+    tags: '**'
+  repository_dispatch:
+    types: request-build-reference # legacy
+  #schedule:
+  #- cron: '0 10 * * *' # Once per day at 10am UTC
+  workflow_dispatch:
+permissions:
+  actions: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # FIXME enable when pushed to spring-projects
+    # if: github.repository_owner == 'spring-projects'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: docs-build
+          fetch-depth: 1
+      - name: Dispatch (partial build)
+        if: github.ref_type == 'branch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+      - name: Dispatch (full build)
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

docs/antora-playbook.yml

@@ -0,0 +1,39 @@
+# PACKAGES [email protected] @antora/atlas-extension:1.0.0-alpha.1 @antora/[email protected] @springio/[email protected] @asciidoctor/[email protected] @opendevise/[email protected]
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+antora:
+  extensions:
+    - '@antora/collector-extension'
+    - require: '@springio/antora-extensions/tabs-migration-extension'
+      unwrap_example_block: always
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'authorization-server'
+    - '@antora/atlas-extension'
+site:
+  title: Spring Authorization Server
+  url: https://https://rwinch.github.io/spring-authorization-server/
+content:
+  sources:
+    - url: ..
+      branches: antora
+      start_path: docs
+      worktrees: true
+asciidoc:
+  attributes:
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+runtime:
+  log:
+    failure_level: warn
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/latest/ui-bundle.zip
+    snapshot: true

docs/antora.yml

@@ -0,0 +1,23 @@
+name: authorization-server
+version: true
+title: Spring Authorization Server
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-authorization-server-docs:generateAntoraYml
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    spring-security-reference-base-url: "https://docs.spring.io/spring-security/reference"
+    spring-security-api-base-url: "https://docs.spring.io/spring-security/site/docs/current/api"
+    spring-boot-reference-base-url: "https://docs.spring.io/spring-boot/docs/current/reference/html"
+    examples-dir: example$docs-src
+    samples-dir: example$samples
+    docs-java: '{examples-dir}/main/java'

docs/modules/ROOT/examples/docs-src

@@ -0,0 +1 @@
+../../../src

docs/modules/ROOT/examples/samples

@@ -0,0 +1 @@
+../../../../samples

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,12 @@
+* xref:index.adoc[]
+* xref:getting-help.adoc[]
+* xref:getting-started.adoc[]
+* xref:configuration-model.adoc[]
+* xref:core-model-components.adoc[]
+* xref:protocol-endpoints.adoc[]
+* xref:how-to.adoc[]
+** xref:guides/how-to-ext-grant-type.adoc[]
+** xref:guides/how-to-jpa.adoc[]
+** xref:guides/how-to-pkce.adoc[]
+** xref:guides/how-to-social-login.adoc[]
+** xref:guides/how-to-userinfo.adoc[]

docs/src/docs/asciidoc/configuration-model.adoc renamed to docs/modules/ROOT/pages/configuration-model.adoc

@@ -6,7 +6,7 @@
 
 `OAuth2AuthorizationServerConfiguration` is a `@Configuration` that provides the minimal default configuration for an OAuth2 authorization server.
 
-`OAuth2AuthorizationServerConfiguration` uses <<customizing-the-configuration, `OAuth2AuthorizationServerConfigurer`>> to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server.
+`OAuth2AuthorizationServerConfiguration` uses xref:configuration-model.adoc#customizing-the-configuration[`OAuth2AuthorizationServerConfigurer`] to apply the default configuration and registers a `SecurityFilterChain` `@Bean` composed of all the infrastructure components supporting an OAuth2 authorization server.
 
 [TIP]
 `OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(HttpSecurity)` is a convenience (`static`) utility method that applies the default OAuth2 security configuration to `HttpSecurity`.
@@ -135,9 +135,9 @@ public SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity h
 <1> `registeredClientRepository()`: The xref:core-model-components.adoc#registered-client-repository[`RegisteredClientRepository`] (*REQUIRED*) for managing new and existing clients.
 <2> `authorizationService()`: The xref:core-model-components.adoc#oauth2-authorization-service[`OAuth2AuthorizationService`] for managing new and existing authorizations.
 <3> `authorizationConsentService()`: The xref:core-model-components.adoc#oauth2-authorization-consent-service[`OAuth2AuthorizationConsentService`] for managing new and existing authorization consents.
-<4> `authorizationServerSettings()`: The <<configuring-authorization-server-settings, `AuthorizationServerSettings`>> (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server.
+<4> `authorizationServerSettings()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerSettings`] (*REQUIRED*) for customizing configuration settings for the OAuth2 authorization server.
 <5> `tokenGenerator()`: The xref:core-model-components.adoc#oauth2-token-generator[`OAuth2TokenGenerator`] for generating tokens supported by the OAuth2 authorization server.
-<6> `clientAuthentication()`: The configurer for <<configuring-client-authentication, OAuth2 Client Authentication>>.
+<6> `clientAuthentication()`: The configurer for xref:configuration-model.adoc#configuring-client-authentication[OAuth2 Client Authentication].
 <7> `authorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-authorization-endpoint[OAuth2 Authorization endpoint].
 <8> `deviceAuthorizationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-authorization-endpoint[OAuth2 Device Authorization endpoint].
 <9> `deviceVerificationEndpoint()`: The configurer for the xref:protocol-endpoints.adoc#oauth2-device-verification-endpoint[OAuth2 Device Verification endpoint].
@@ -186,7 +186,7 @@ public final class AuthorizationServerSettings extends AbstractSettings {
 `AuthorizationServerSettings` is a *REQUIRED* component.
 
 [TIP]
-<<default-configuration, `@Import(OAuth2AuthorizationServerConfiguration.class)`>> automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided.
+xref:configuration-model.adoc#default-configuration[`@Import(OAuth2AuthorizationServerConfiguration.class)`] automatically registers an `AuthorizationServerSettings` `@Bean`, if not already provided.
 
 The following example shows how to customize the configuration settings and register an `AuthorizationServerSettings` `@Bean`:
 

docs/src/docs/asciidoc/core-model-components.adoc renamed to docs/modules/ROOT/pages/core-model-components.adoc

@@ -141,7 +141,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-authorization]]
 == OAuth2Authorization
 
-An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a <<registered-client, client>>, by the resource owner or itself in the case of the `client_credentials` authorization grant type.
+An `OAuth2Authorization` is a representation of an OAuth2 authorization, which holds state related to the authorization granted to a xref:core-model-components.adoc#registered-client[client], by the resource owner or itself in the case of the `client_credentials` authorization grant type.
 
 [TIP]
 The corresponding authorization model in Spring Security's OAuth2 Client support is {spring-security-reference-base-url}/servlet/oauth2/client/core.html#oauth2Client-authorized-client[OAuth2AuthorizedClient].
@@ -174,7 +174,7 @@ public class OAuth2Authorization implements Serializable {
 }
 ----
 <1> `id`: The ID that uniquely identifies the `OAuth2Authorization`.
-<2> `registeredClientId`: The ID that uniquely identifies the <<registered-client, RegisteredClient>>.
+<2> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient].
 <3> `principalName`: The principal name of the resource owner (or client).
 <4> `authorizationGrantType`: The `AuthorizationGrantType` used.
 <5> `authorizedScopes`: The `Set` of scope(s) authorized for the client.
@@ -236,7 +236,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-authorization-consent]]
 == OAuth2AuthorizationConsent
 
-An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a <<registered-client, client>> by the resource owner.
+An `OAuth2AuthorizationConsent` is a representation of an authorization "consent" (decision) from an https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1[OAuth2 authorization request flow] – for example, the `authorization_code` grant, which holds the authorities granted to a xref:core-model-components.adoc#registered-client[client] by the resource owner.
 
 When authorizing access to a client, the resource owner may grant only a subset of the authorities requested by the client.
 The typical use case is the `authorization_code` grant flow, in which the client requests scope(s) and the resource owner grants (or denies) access to the requested scope(s).
@@ -256,7 +256,7 @@ public final class OAuth2AuthorizationConsent implements Serializable {
 
 }
 ----
-<1> `registeredClientId`: The ID that uniquely identifies the <<registered-client, RegisteredClient>>.
+<1> `registeredClientId`: The ID that uniquely identifies the xref:core-model-components.adoc#registered-client[RegisteredClient].
 <2> `principalName`: The principal name of the resource owner.
 <3> `authorities`: The authorities granted to the client by the resource owner. An authority can represent a scope, a claim, a permission, a role, and others.
 
@@ -308,7 +308,7 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-token-context]]
 == OAuth2TokenContext
 
-An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an <<oauth2-token-generator, OAuth2TokenGenerator>> and <<oauth2-token-customizer, OAuth2TokenCustomizer>>.
+An `OAuth2TokenContext` is a context object that holds information associated with an `OAuth2Token` and is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] and xref:core-model-components.adoc#oauth2-token-customizer[OAuth2TokenCustomizer].
 
 `OAuth2TokenContext` provides the following accessors:
 
@@ -337,10 +337,10 @@ public interface OAuth2TokenContext extends Context {
 
 }
 ----
-<1> `getRegisteredClient()`: The <<registered-client, RegisteredClient>> associated with the authorization grant.
+<1> `getRegisteredClient()`: The xref:core-model-components.adoc#registered-client[RegisteredClient] associated with the authorization grant.
 <2> `getPrincipal()`: The `Authentication` instance of the resource owner (or client).
 <3> `getAuthorizationServerContext()`: The xref:configuration-model.adoc#configuring-authorization-server-settings[`AuthorizationServerContext`] object that holds information of the Authorization Server runtime environment.
-<4> `getAuthorization()`: The <<oauth2-authorization, OAuth2Authorization>> associated with the authorization grant.
+<4> `getAuthorization()`: The xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization] associated with the authorization grant.
 <5> `getAuthorizedScopes()`: The scope(s) authorized for the client.
 <6> `getTokenType()`: The `OAuth2TokenType` to generate. The supported values are `code`, `access_token`, `refresh_token`, and `id_token`.
 <7> `getAuthorizationGrantType()`: The `AuthorizationGrantType` associated with the authorization grant.
@@ -349,7 +349,7 @@ public interface OAuth2TokenContext extends Context {
 [[oauth2-token-generator]]
 == OAuth2TokenGenerator
 
-An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided <<oauth2-token-context, OAuth2TokenContext>>.
+An `OAuth2TokenGenerator` is responsible for generating an `OAuth2Token` from the information contained in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext].
 
 The `OAuth2Token` generated primarily depends on the type of `OAuth2TokenType` specified in the `OAuth2TokenContext`.
 
@@ -360,11 +360,11 @@ For example, when the `value` for `OAuth2TokenType` is:
 * `refresh_token`, then `OAuth2RefreshToken` is generated.
 * `id_token`, then `OidcIdToken` is generated.
 
-Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the <<registered-client, RegisteredClient>>.
+Furthermore, the format of the generated `OAuth2AccessToken` varies, depending on the `TokenSettings.getAccessTokenFormat()` configured for the xref:core-model-components.adoc#registered-client[RegisteredClient].
 If the format is `OAuth2TokenFormat.SELF_CONTAINED` (the default), then a `Jwt` is generated.
 If the format is `OAuth2TokenFormat.REFERENCE`, then an "opaque" token is generated.
 
-Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from <<oauth2-authorization, OAuth2Authorization.Token.getClaims()>>.
+Finally, if the generated `OAuth2Token` has a set of claims and implements `ClaimAccessor`, the claims are made accessible from xref:core-model-components.adoc#oauth2-authorization[OAuth2Authorization.Token.getClaims()].
 
 The `OAuth2TokenGenerator` is primarily used by components that implement authorization grant processing – for example, `authorization_code`, `client_credentials`, and `refresh_token`.
 
@@ -419,8 +419,8 @@ The `OAuth2AuthorizationServerConfigurer` is useful when applying multiple confi
 [[oauth2-token-customizer]]
 == OAuth2TokenCustomizer
 
-An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided <<oauth2-token-context, OAuth2TokenContext>>.
-It is used by an <<oauth2-token-generator, OAuth2TokenGenerator>> to let it customize the attributes of the `OAuth2Token` before it is generated.
+An `OAuth2TokenCustomizer` provides the ability to customize the attributes of an `OAuth2Token`, which are accessible in the provided xref:core-model-components.adoc#oauth2-token-context[OAuth2TokenContext].
+It is used by an xref:core-model-components.adoc#oauth2-token-generator[OAuth2TokenGenerator] to let it customize the attributes of the `OAuth2Token` before it is generated.
 
 An `OAuth2TokenCustomizer<OAuth2TokenClaimsContext>` declared with a generic type of `OAuth2TokenClaimsContext` (`implements OAuth2TokenContext`) provides the ability to customize the claims of an "opaque" `OAuth2AccessToken`.
 `OAuth2TokenClaimsContext.getClaims()` provides access to the `OAuth2TokenClaimsSet.Builder`, allowing the ability to add, replace, and remove claims.
@@ -492,7 +492,7 @@ public OAuth2TokenCustomizer<JwtEncodingContext> jwtCustomizer() {
 If the `OAuth2TokenGenerator` is not provided as a `@Bean` or is not configured through the `OAuth2AuthorizationServerConfigurer`, an `OAuth2TokenCustomizer<JwtEncodingContext>` `@Bean` will automatically be configured with a `JwtGenerator`.
 
 [TIP]
-For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc#how-to-userinfo[How-to: Customize the OpenID Connect 1.0 UserInfo response].
+For an example showing how you can xref:guides/how-to-userinfo.adoc#customize-id-token[customize the ID token], see the guide xref:guides/how-to-userinfo.adoc[How-to: Customize the OpenID Connect 1.0 UserInfo response].
 
 [[session-registry]]
 == SessionRegistry

docs/src/docs/asciidoc/getting-help.adoc renamed to docs/modules/ROOT/pages/getting-help.adoc

@@ -1,5 +1,6 @@
 [[getting-help]]
 = Getting Help
+:page-section-summary-toc: 1
 
 [[community]]
 == Community

docs/src/docs/asciidoc/getting-started.adoc renamed to docs/modules/ROOT/pages/getting-started.adoc

@@ -1,4 +1,3 @@
-include::attributes.adoc[]
 
 [[getting-started]]
 = Getting Started
@@ -19,8 +18,11 @@ The easiest way to begin using Spring Authorization Server is by creating a http
 You can use https://start.spring.io[start.spring.io] to generate a basic project or use the https://github.com/spring-projects/spring-authorization-server/tree/main/samples/default-authorizationserver[default authorization server sample] as a guide.
 Then add Spring Boot's starter for Spring Authorization Server as a dependency:
 
+[tabs]
+======
+Maven::
++
 [[spring-boot-maven-dependency]]
-.Maven
 [source,xml,role="primary",subs="attributes,verbatim"]
 ----
 <dependency>
@@ -29,19 +31,24 @@ Then add Spring Boot's starter for Spring Authorization Server as a dependency:
 </dependency>
 ----
 
+Gradle::
++
 [[spring-boot-gradle-dependency]]
-.Gradle
 [source,gradle,role="secondary",subs="attributes,verbatim"]
 ----
 implementation "org.springframework.boot:spring-boot-starter-oauth2-authorization-server"
 ----
+======
 
 TIP: See https://docs.spring.io/spring-boot/docs/current/reference/html/getting-started.html#getting-started.installing[Installing Spring Boot] for more information on using Spring Boot with Maven or Gradle.
 
 Alternatively, you can add Spring Authorization Server without Spring Boot using the following example:
 
+[tabs]
+======
+Maven::
++
 [[maven-dependency]]
-.Maven
 [source,xml,role="primary",subs="attributes,verbatim"]
 ----
 <dependency>
@@ -51,12 +58,14 @@ Alternatively, you can add Spring Authorization Server without Spring Boot using
 </dependency>
 ----
 
+Gradle::
++
 [[gradle-dependency]]
-.Gradle
 [source,gradle,role="secondary",subs="attributes,verbatim"]
 ----
 implementation "org.springframework.security:spring-security-oauth2-authorization-server:{spring-authorization-server-version}"
 ----
+======
 
 [[developing-your-first-application]]
 == Developing Your First Application
@@ -67,10 +76,10 @@ To get started, you need the minimum required components defined as a `@Bean`. W
 .application.yml
 [source,yaml]
 ----
-include::{docs-java}/sample/gettingStarted/application.yml[]
+include::{docs-java}/sample/gettingstarted/application.yml[]
 ----
 
-TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The <<defining-required-components,next section>> demonstrates providing all of the necessary beans yourself.
+TIP: Beyond the Getting Started experience, most users will want to customize the default configuration. The xref:getting-started.adoc#defining-required-components[next section] demonstrates providing all of the necessary beans yourself.
 
 [[defining-required-components]]
 == Defining Required Components
@@ -83,7 +92,7 @@ These components can be defined as follows:
 .SecurityConfig.java
 [source,java]
 ----
-include::{docs-java}/sample/gettingStarted/SecurityConfig.java[]
+include::{docs-java}/sample/gettingstarted/SecurityConfig.java[]
 ----
 
 This is a minimal configuration for getting started quickly. To understand what each component is used for, see the following descriptions: