Switch to Antora documentation site

spring-graphql-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)

spring-graphql-docs/antora-playbook.yml

@@ -0,0 +1,41 @@
+antora:
+  extensions:
+    - '@springio/antora-extensions/partial-build-extension'
+    # - require: '@springio/antora-extensions/latest-version-extension'
+    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
+    - '@antora/collector-extension'
+    - '@antora/atlas-extension'
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'graphql'
+site:
+  title: Spring GraphQL
+  url: https://rwinch.github.io/spring-graphql
+  robots: allow
+git:
+  ensure_git_suffix: false
+content:
+  sources:
+    - url: ./..
+      branches: HEAD
+      start_path: spring-graphql-docs
+      worktrees: true
+asciidoc:
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/spring-graphql
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+urls:
+  latest_version_segment_strategy: redirect:to
+  latest_version_segment: ''
+  redirect_facility: httpd
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip
+    snapshot: true
+runtime:
+  log:
+    failure_level: warn

spring-graphql-docs/antora.yml

@@ -0,0 +1,31 @@
+name: graphql
+version: true
+title: Spring GraphQL
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-graphql-docs:generateAntoraYml
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    docs-site: https://docs.spring.io
+    include-java: 'example$docs-src/main/java/org/springframework/graphql/docs'
+    github-tag: main
+    github-repo: spring-projects/spring-graphql
+    github-raw: https://raw.githubusercontent.com/{github-repo}/{github-tag}
+    github-issues: https://github.com/{github-repo}/issues/
+    github-main-branch: https://github.com/{github-repo}/tree/main
+    github-10x-branch: https://github.com/{github-repo}/tree/1.0.x
+    github-wiki: https://github.com/{github-repo}/wiki
+    graphql-java-docs: https://www.graphql-java.com/documentation
+    javadoc: https://docs.spring.io/spring-graphql/docs/{spring-graphql-version}/api
+    # version attributes from main build.gradle
+    spring-framework-ref-docs: https://docs.spring.io/spring-framework/reference
+    spring-boot-ref-docs: https://docs.spring.io/spring-boot/docs/{spring-boot-version}/reference/html

spring-graphql-docs/build.gradle

@@ -1,6 +1,7 @@
 plugins {
 	id 'java-library'
-	id 'org.asciidoctor.jvm.convert' version '3.3.2'
+	id 'org.antora' version '1.0.0'
+	id 'io.spring.antora.generate-antora-yml' version '0.0.1'
 }
 
 description = "Spring for GraphQL reference documentation"
@@ -12,7 +13,6 @@ configurations {
 		visible = false
 	}
 	matching { it.name.endsWith("Classpath") }.all { it.extendsFrom(dependencyManagement) }
-	asciidoctorExtensions
 }
 
 dependencies {
@@ -25,7 +25,6 @@ dependencies {
 	api 'org.springframework:spring-messaging'
 	api 'org.springframework.data:spring-data-commons'
 	api 'com.querydsl:querydsl-core'
-	asciidoctorExtensions 'io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.4'
 }
 
 jar {
@@ -77,42 +76,44 @@ task api(type: Javadoc) {
 	destinationDir = file("$buildDir/docs/javadoc")
 }
 
+antora {
+	version = '3.2.0-alpha.2'
+	options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true]
+		environment = [
+			'ALGOLIA_API_KEY': '9d489079e5ec46dbb238909fee5c9c29',
+			'ALGOLIA_APP_ID': 'WB1FQYI187',
+			'ALGOLIA_INDEX_NAME': 'springsecurity',
+	]
+	dependencies = [
+			'@antora/atlas-extension': '1.0.0-alpha.1',
+			'@antora/collector-extension': '1.0.0-alpha.3',
+			'@asciidoctor/tabs': '1.0.0-beta.3',
+			'@springio/antora-extensions': '1.4.2',
+			'@springio/asciidoctor-extensions': '1.0.0-alpha.8',
+			'@opendevise/antora-release-line-extension': '1.0.0',
+	]
+}
 
-/**
- * Generate the Spring for GraphQL Reference documentation from "src/docs/asciidoc"
- * in "build/docs/reference/html".
- */
-asciidoctor {
-	configurations 'asciidoctorExtensions'
-	baseDirFollowsSourceDir()
-	sources {
-		include 'index.adoc'
-	}
-	logDocuments = true
-	outputOptions {
-		backends "spring-html"
-	}
-	outputDir "$buildDir/docs/reference/html"
-	attributes 'spring-graphql-version': project.version,
-			'spring-boot-version': springBootVersion,
-			'spring-framework-version': springFrameworkVersion
+tasks.named("generateAntoraYml") {
+	asciidocAttributes = project.provider( { ['spring-graphql-version': project.version,
+		'spring-boot-version': springBootVersion,
+		'spring-framework-version': springFrameworkVersion] } )
 }
 
-asciidoctor.mustRunAfter "check"
+tasks.named("antora") {
+	mustRunAfter "check"
+}
 
 /**
  * Zip all docs into a single archive
  */
-task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor']) {
+task docsZip(type: Zip, dependsOn: ['api']) {
 	group = "Distribution"
 	description = "Builds -${archiveClassifier} archive containing api and reference " +
 			"for deployment at https://docs.spring.io/spring-graphql/docs."
 	from (api) {
 		into "api"
 	}
-	from ("$asciidoctor.outputDir") {
-		into "reference/html"
-	}
 }
 
 publishing {

spring-graphql-docs/modules/ROOT/examples/docs-src

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

spring-graphql-docs/modules/ROOT/nav.adoc

@@ -0,0 +1,13 @@
+* xref:index.adoc[Overview]
+* xref:transports.adoc[]
+* xref:request-execution.adoc[]
+* xref:data.adoc[]
+* xref:controllers.adoc[]
+* xref:security.adoc[]
+* xref:observability.adoc[]
+* xref:graalvm-native.adoc[]
+* xref:client.adoc[]
+* xref:graphiql.adoc[]
+* xref:testing.adoc[]
+* xref:boot-starter.adoc[]
+* xref:samples.adoc[]

spring-graphql-docs/modules/ROOT/pages/boot-starter.adoc

@@ -0,0 +1,21 @@
+[[boot-starter]]
+= Boot Starter
+
+Spring Boot provides a starter for building GraphQL applications with Spring for GraphQL.
+For version information, see the
+https://github.com/spring-projects/spring-graphql/wiki/Spring-for-GraphQL-Versions[Spring for GraphQL Versions] wiki page.
+
+The easiest way to get started is via https://start.spring.io by selecting
+"Spring for GraphQL" along with an underlying transport such as Spring MVC of WebFlux over
+HTTP or WebSocket, or over RSocket. Refer to the
+https://docs.spring.io/spring-boot/docs/current/reference/html/web.html#web.graphql[Spring for GraphQL Starter]
+section in the Spring Boot reference for details on supported transports, auto-configuration related
+features, and more. For testing support, see
+https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.testing.spring-boot-applications.spring-graphql-tests[Auto-Configured GraphQL Tests].
+
+For further reference, check the following GraphQL related:
+
+- https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.metrics.supported.spring-graphql[Metrics]
+- https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties.web[Properties]
+- https://docs.spring.io/spring-boot/docs/current/reference/html/auto-configuration-classes.html#appendix.auto-configuration-classes.core[Auto-Configuration Classes]
+

spring-graphql-docs/src/docs/asciidoc/includes/client.adoc → spring-graphql-docs/modules/ROOT/pages/client.adoc

@@ -16,15 +16,15 @@ build time.
 
 To create a `GraphQlClient` you need one of the following extensions:
 
-- <<client.httpgraphqlclient, HttpGraphQlClient>>
-- <<client.websocketgraphqlclient, WebSocketGraphQlClient>>
-- <<client.rsocketgraphqlclient, RSocketGraphQlClient>>
+- xref:client.adoc#client.httpgraphqlclient[HttpGraphQlClient]
+- xref:client.adoc#client.websocketgraphqlclient[WebSocketGraphQlClient]
+- xref:client.adoc#client.rsocketgraphqlclient[RSocketGraphQlClient]
 
 Each defines a `Builder` with options relevant to the transport. All builders extend
-from a common, base GraphQlClient <<client.graphqlclient.builder, `Builder`>> with options
+from a common, base GraphQlClient xref:client.adoc#client.graphqlclient.builder[`Builder`] with options
 relevant to all extensions.
 
-Once you have a `GraphQlClient` you can begin to make <<client.requests, requests>>.
+Once you have a `GraphQlClient` you can begin to make xref:client.adoc#client.requests[requests].
 
 
 [[client.httpgraphqlclient]]
@@ -41,7 +41,7 @@ HttpGraphQlClient graphQlClient = HttpGraphQlClient.create(webClient);
 ----
 
 Once `HttpGraphQlClient` is created, you can begin to
-<<client.requests, execute requests>> using the same API, independent of the underlying
+xref:client.adoc#client.requests[execute requests] using the same API, independent of the underlying
 transport. If you need to change any transport specific details, use `mutate()` on an
 existing `HttpGraphQlClient` to create a new instance with customized settings:
 
@@ -97,7 +97,7 @@ single, shared connection for all requests to that server. Each client instance
 establishes its own connection and that is typically not the intent for a single server.
 
 Once `WebSocketGraphQlClient` is created, you can begin to
-<<client.requests, execute requests>> using the same API, independent of the underlying
+xref:client.adoc#client.requests[execute requests] using the same API, independent of the underlying
 transport. If you need to change any transport specific details, use `mutate()` on an
 existing `WebSocketGraphQlClient` to create a new instance with customized settings:
 
@@ -149,7 +149,7 @@ For WebSocket transport specific interception, you can create a
 	}
 ----
 
-<<client.interception,Register>> the above interceptor as any other
+xref:client.adoc#client.interception[Register] the above interceptor as any other
 `GraphQlClientInterceptor` and use it also to intercept GraphQL requests, but note there
 can be at most one interceptor of type `WebSocketGraphQlClientInterceptor`.
 
@@ -187,7 +187,7 @@ single, shared session for all requests to that server. Each client instance
 establishes its own connection and that is typically not the intent for a single server.
 
 Once `RSocketGraphQlClient` is created, you can begin to
-<<client.requests, execute requests>> using the same API, independent of the underlying
+xref:client.adoc#client.requests[execute requests] using the same API, independent of the underlying
 transport.
 
 
@@ -199,16 +199,16 @@ transport.
 builders of all extensions. Currently, it has lets you configure:
 
 - `DocumentSource` strategy to load the document for a request from a file
-- <<client.interception>> of executed requests
+- xref:client.adoc#client.interception[Interception] of executed requests
 
 
 
 
 [[client.requests]]
 == Requests
 
-Once you have a <<client.graphqlclient>>, you can begin to perform requests via
-<<client.requests.retrieve, retrieve()>> or <<client.requests.execute, execute()>>
+Once you have a xref:client.adoc#client.graphqlclient[`GraphQlClient`], you can begin to perform requests via
+xref:client.adoc#client.requests.retrieve[retrieve()] or xref:client.adoc#client.requests.execute[execute()]
 where the former is only a shortcut for the latter.
 
 
@@ -239,7 +239,7 @@ The below retrieves and decodes the data for a query:
 
 The input document is a `String` that could be a literal or produced through a code
 generated request object. You can also define documents in files and use a
-<<client.requests.document-source>> to resole them by file name.
+xref:client.adoc#client.requests.document-source[Document Source] to resole them by file name.
 
 The path is relative to the "data" key and uses a simple dot (".") separated notation
 for nested fields with optional array indices for list elements, e.g. `"project.name"`
@@ -267,7 +267,7 @@ response and the field:
 [[client.requests.execute]]
 === Execute
 
-<<client.requests.retrieve>> is only a shortcut to decode from a single path in the
+xref:client.adoc#client.requests.retrieve[Retrieve] is only a shortcut to decode from a single path in the
 response map. For more control, use the `execute` method and handle the response:
 
 For example:
@@ -341,7 +341,7 @@ You can then:
 
 The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.
 
-You can use the `GraphQlClient` <<client.graphqlclient.builder>> to customize the
+You can use the `GraphQlClient` xref:client.adoc#client.graphqlclient.builder[Builder] to customize the
 `DocumentSource` for loading documents by names.
 
 
@@ -352,16 +352,16 @@ You can use the `GraphQlClient` <<client.graphqlclient.builder>> to customize th
 
 `GraphQlClient` can execute subscriptions over transports that support it. Only
 the WebSocket and RSocket transports support GraphQL subscriptions, so you'll need to
-create a <<client.websocketgraphqlclient,WebSocketGraphQlClient>> or
-<<client.rsocketgraphqlclient,RSocketGraphQlClient>>.
+create a xref:client.adoc#client.websocketgraphqlclient[WebSocketGraphQlClient] or
+xref:client.adoc#client.rsocketgraphqlclient[RSocketGraphQlClient].
 
 
 
 [[client.subscriptions.retrieve]]
 === Retrieve
 
 To start a subscription stream, use `retrieveSubscription` which is similar to
-<<client.requests.retrieve,retrieve>> for a single response but returning a stream of
+xref:client.adoc#client.requests.retrieve[retrieve] for a single response but returning a stream of
 responses, each decoded to some data:
 
 [source,java,indent=0,subs="verbatim,quotes"]
@@ -390,7 +390,7 @@ provides access to the `Subscription`.
 [[client.subscriptions.execute]]
 === Execute
 
-<<client.subscriptions.retrieve>> is only a shortcut to decode from a single path in each
+xref:client.adoc#client.subscriptions.retrieve[Retrieve] is only a shortcut to decode from a single path in each
 response map. For more control, use the `executeSubscription` method and handle each
 response directly: