Migrated docs to antora

.github/workflows/deploy-docs.yml

@@ -0,0 +1,31 @@
+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
+    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)

build.gradle

@@ -30,8 +30,10 @@ buildscript {
 
 // TODO: remove this hack, see: https://github.com/nebula-plugins/nebula-release-plugin/issues/213
 def releaseStage = findProperty('release.stage')
-apply plugin: 'nebula.release'
-release.defaultVersionStrategy = nebula.plugin.release.git.opinion.Strategies.SNAPSHOT
+if (!project.hasProperty("antora")) {
+	apply plugin: 'nebula.release'
+	release.defaultVersionStrategy = nebula.plugin.release.git.opinion.Strategies.SNAPSHOT
+}
 
 apply plugin: 'io.github.gradle-nexus.publish-plugin'
 apply from: 'dependencies.gradle'
@@ -58,6 +60,10 @@ subprojects {
 		apply plugin: 'io.spring.javaformat'
 		apply plugin: 'me.champeau.jmh'
 
+		nohttp {
+			source.exclude "**/build/**"
+		}
+
 		java {
 			// It is more idiomatic to define different features for different sets of optional
 			// dependencies, e.g., 'dropwizard' and 'reactor'. If this library published Gradle
@@ -284,8 +290,10 @@ subprojects {
 		apply plugin: 'com.netflix.nebula.maven-apache-license'
 		apply plugin: 'com.netflix.nebula.publish-verification'
 		apply plugin: 'com.netflix.nebula.contacts'
-		apply plugin: 'com.netflix.nebula.info'
-		apply plugin: 'com.netflix.nebula.project'
+		if (!project.hasProperty("antora")) {
+			apply plugin: 'com.netflix.nebula.info'
+			apply plugin: 'com.netflix.nebula.project'
+		}
 
 		if (project.name != 'micrometer-tracing-bom') {
 			jar {
@@ -328,7 +336,8 @@ subprojects {
 	}
 
 	def check = tasks.findByName('check')
-	if (check) project.rootProject.tasks.releaseCheck.dependsOn check
+	boolean antora = project.hasProperty("antora")
+	if (check && !antora) project.rootProject.tasks.releaseCheck.dependsOn check
 }
 
 nexusPublishing {

config/checkstyle/checkstyle-suppressions.xml

@@ -4,4 +4,7 @@
 		"https://checkstyle.org/dtds/suppressions_1_2.dtd">
 <suppressions>
 	<suppress files=".*Slf4j.*" checks="SLF4JIllegalImportCheck"/>
+
+	<suppress id="sysout" files="[\\/]samples[\\/].*"/>
+	<suppress id="sysout" files="[\\/]src[\\/]test[\\/].*"/>
 </suppressions>

docs/antora-playbook.yml

@@ -0,0 +1,43 @@
+# 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:
+    - '@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: 'tracing'
+site:
+  title: Micrometer Tracing
+  url: https://docs.micrometer.io/micrometer/reference/
+content:
+  sources:
+    - url: ./..
+      branches: HEAD
+      start_path: docs
+      worktrees: true
+asciidoc:
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/micrometer
+    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
+    format: pretty
+ui:
+  bundle:
+    url: https://github.com/rwinch/antora-ui-micrometer/releases/download/latest/ui-bundle.zip
+    snapshot: true
+

docs/antora.yml

@@ -0,0 +1,20 @@
+name: tracing
+version: true
+title: Micrometer Tracing
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q -PbuildSrc.skipTests=true -Pantora "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :docs:generateAntoraResources
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    include-java: 'example$docs-src/test/java/io/micrometer/docs'
+    include-bridges-java: 'example$bridges-src'
+    include-resources: 'example$docs-src/test/resources'

docs/build.gradle

@@ -0,0 +1,75 @@
+plugins {
+    id 'java'
+    id 'io.spring.antora.generate-antora-yml' version '0.0.1'
+    id 'org.antora' version '1.0.0'
+    id 'java-library'
+}
+
+description = "Micrometer Tracing Docs"
+
+antora {
+	version = '3.2.0-alpha.2'
+	playbook = 'antora-playbook.yml'
+	options = ['--clean', '--stacktrace']
+	environment = [
+			'ALGOLIA_API_KEY': 'da671ceec1f84f80f280884a6a91bde5',
+			'ALGOLIA_APP_ID': 'WB1FQYI187',
+			'ALGOLIA_INDEX_NAME': 'micrometer'
+	]
+
+	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',
+	]
+}
+
+
+tasks.named("generateAntoraYml") {
+    asciidocAttributes = project.provider( {
+        return  ["micrometer-tracing-version": project.version.toString()]
+    } )
+}
+
+tasks.create("generateAntoraResources") {
+    dependsOn 'generateAntoraYml'
+}
+
+tasks.named("antora") {
+    dependsOn "generateAntoraResources"
+}
+
+tasks.named("antora") {
+    dependsOn "test"
+}
+
+jar {
+    enabled = false
+}
+
+javadoc {
+    enabled = false
+}
+
+repositories {
+   mavenCentral()
+}
+
+dependencies {
+    implementation project(":micrometer-tracing")
+    implementation 'ch.qos.logback:logback-classic'
+    implementation 'org.slf4j:slf4j-api'
+
+    testImplementation 'io.zipkin.reporter2:zipkin-sender-urlconnection'
+
+    testImplementation project(":micrometer-tracing-test")
+    testImplementation project(":micrometer-tracing-integration-test")
+    testImplementation 'org.aspectj:aspectjweaver'
+    testImplementation 'org.junit.jupiter:junit-jupiter'
+    testImplementation 'org.mockito:mockito-inline'
+    testImplementation 'org.assertj:assertj-core'
+    testImplementation 'org.springframework:spring-context'
+}
+

docs/modules/ROOT/examples/bridges-src

@@ -0,0 +1 @@
+../../../../micrometer-tracing-bridges/

docs/modules/ROOT/examples/docs-src

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

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,7 @@
+* xref:index.adoc[Micrometer Tracing]
+* xref:glossary.adoc[Glossary]
+* xref:tracers.adoc[Supported Tracers]
+* xref:reporters.adoc[Supported Reporters]
+* xref:api.adoc[Micrometer Tracing API]
+* xref:configuring.adoc[Micrometer Observation Configuration]
+* xref:testing.adoc[Testing]

docs/modules/ROOT/pages/api.adoc

@@ -0,0 +1,94 @@
+== Using Micrometer Tracing Directly
+
+In this section we will describe how to use the Micrometer Tracing API directly to create and report spans.
+
+=== Micrometer Tracing Examples
+
+Below you can see basic operations on a span. Please read the comments in the snippet for details.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=manual_span_creation,indent=0]
+-----
+
+Below you can see how to continue a span in a new thread, that was started in another thread.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=manual_span_continuation,indent=0]
+-----
+
+Below you can see how to create a child span when explicitly knowing who the parent span is.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=manual_span_joining,indent=0]
+-----
+
+=== Micrometer Tracing Brave Setup
+
+In this subsection we will set up Micrometer Tracing with Brave.
+
+Below you can see how to create a Micrometer Tracing `Tracer` using Brave components that would send completed spans to Zipkin.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=brave_setup,indent=0]
+-----
+
+=== Micrometer Tracing OpenTelemetry Setup
+
+In this subsection we will set up Micrometer Tracing with OpenTelemetry (OTel).
+
+Below you can see how to create a Micrometer Tracing `Tracer` using OTel components that would send completed spans to Zipkin.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=otel_setup,indent=0]
+-----
+
+=== Micrometer Tracing Baggage API
+
+Traces connect from service to service using header propagation. Besides trace identifiers, other properties (called `Baggage`) can also be passed along with the request.
+
+Below you can find an example on how to use the Tracer API to create and extract baggage.
+
+[source,java,subs=+attributes]
+-----
+include::{include-bridges-java}/micrometer-tracing-bridge-brave/src/test/java/io/micrometer/tracing/brave/bridge/BraveTracingApiTests.java[tags=baggage_api,indent=0]
+-----
+
+IMPORTANT: For Brave, remember to set up the `PropagationFactory` so that it contains the baggage fields that you will be using in your code. Check the example below for details.
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingApiTests.java[tags=baggage_brave_setup,indent=0]
+-----
+
+=== Aspect Oriented Programming
+
+Micrometer Tracing contains a `@NewSpan`, `@ContinueSpan` and `@SpanTag` annotations that frameworks can use to create or customize spans for either specific types of methods such as those serving web request endpoints or, more generally, to all methods.
+
+WARNING: Micrometer's Spring Boot configuration does _not_ recognize these aspects on arbitrary methods.
+
+An incubating AspectJ aspect is included. You can use it in your application either through compile/load time AspectJ weaving or through framework facilities that interpret AspectJ aspects and proxy targeted methods in some other way, such as Spring AOP. Here is a sample Spring AOP configuration:
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingSpanAspectTests.java[tags=spring_config,indent=0]
+-----
+
+Applying `SpanAspect` makes `@NewSpan` and `@ContinueSpan` usable on any arbitrary method in an AspectJ proxied instance, as the following example shows:
+
+[source,java,subs=+attributes]
+-----
+include::{include-java}/tracing/TracingSpanAspectTests.java[tags=example,indent=0]
+
+// --------------------------
+// ----- USAGE EXAMPLE ------
+// --------------------------
+
+include::{include-java}/tracing/TracingSpanAspectTests.java[tags=usage_example,indent=0]
+
+-----
+