Lots of 3.0 documentation updates (#5261)

* Update all REST API endpoint references

* Removed docs about generating client SDK (feature removed for now)

* rename client to sdk

* Build using local playbook

* Updates to core documentation for 3.0

* Lots of changes to docs for the 3.0 release

* Lots more docs changes

docs-playbook/Dockerfile

@@ -4,8 +4,8 @@
 FROM ubuntu:latest
 
 ENV BASE_DIR=/repository/docs-playbook
-ENV PLAYBOOK docs-playbook.yml
-ENV SEARCH_PLAYBOOK search-playbook.yml
+ENV PLAYBOOK=docs-playbook.yml
+ENV SEARCH_PLAYBOOK=search-playbook.yml
 
 VOLUME /repository
 

docs-playbook/_build-all-local.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+# Build the docker image
+docker build -t="apicurio/apicurio-docs-builder" --rm .
+
+# Use the docker image to build the docs
+docker run --env PLAYBOOK=local-test-playbook.yml --env SEARCH_PLAYBOOK=local-test-playbook.yml -v $(pwd)/..:/repository apicurio/apicurio-docs-builder:latest

docs-playbook/docs-playbook.yml

@@ -6,7 +6,7 @@ site:
 content:
   sources:
   - url: https://github.com/Apicurio/apicurio-registry.git
-    branches: 2.6.x,2.5.x,2.4.x,2.3.x,2.2.x,2.1.x,2.0.x,1.3.x
+    branches: main,2.6.x,2.5.x,2.4.x,2.3.x,2.2.x,2.1.x,2.0.x,1.3.x
     start_path: docs
     edit_url: '{web_url}'
   - url: https://github.com/Apicurio/apicurio-registry-operator.git

docs-playbook/local-test-playbook.yml

@@ -0,0 +1,41 @@
+site:
+  title: Apicurio Registry PREVIEW
+  # the 404 page and sitemap files only get generated when the url property is set
+  url: https://www.apicur.io/registry/docs
+  start_page: apicurio-registry::index.adoc
+content:
+  sources:
+  - url: ../
+    branches: HEAD
+    start_path: docs
+
+ui:
+  bundle:
+    url: https://raw.githubusercontent.com/Apicurio/apicurio-docs-ui/main/dist/ui-bundle.zip
+    snapshot: true
+
+runtime:
+  cache_dir: ./target/antora-cache
+
+output:
+  dir: ./target/dist
+
+asciidoc:
+  attributes:
+    plantuml-server-url: 'http://www.plantuml.com/plantuml'
+    plantuml-fetch-diagram: true
+    mod-loc: partial$
+    registry-overview: link:assembly-intro-to-the-registry.html[Introduction to Apicurio Registry]
+    registry-rules: link:assembly-intro-to-registry-rules.html[Introduction to Apicurio Registry rules]
+    registry-artifact-reference: link:assembly-artifact-reference.html[Apicurio Registry artifact reference]
+    registry-rule-reference: link:assembly-rule-reference.html[Apicurio Registry rule reference]
+    registry-config-reference: link:assembly-config-reference.html[Apicurio Registry configuration reference]
+    installing-the-registry-docker: link:assembly-installing-registry-docker.html[Installing Apicurio Registry using Docker]
+    installing-the-registry-openshift: link:assembly-installing-registry-openshift.html[Installing Apicurio Registry on OpenShift]
+    installing-the-registry-storage-openshift: link:assembly-installing-registry-storage-openshift.html[Installing Apicurio Registry storage on OpenShift]
+    managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console]
+    managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API]
+    managing-registry-artifacts-maven: link:assembly-managing-registry-artifacts-maven.html[Managing Apicurio Registry content using the Maven plug-in]
+    sdk:  link:assembly-using-the-registry-sdk.html[Managing Apicurio Registry content using an SDK]
+    kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers in Java clients]
+    registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java applications]

docs-playbook/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apicurio-docs-playbook",
-  "version": "1.0.0",
+  "version": "3.0.0",
   "description": "This folder contains the configuration and scripts used when building the Apicurio Registry  documentation for publishing to the Apicurio project web site.  We are using a tool called Antora to build the asciidoc based documentation into a publishable site.  However, due to some issues with building on various platforms (I'm looking at you, Windows) and also some conflicts between what Antora builds and what our GitHub Pages (jekyll) project site expects, we have created a non-trivial (but automated) process for building the docs.",
   "main": "index.js",
   "scripts": {

docs-playbook/search-playbook.yml

@@ -6,7 +6,7 @@ site:
 content:
   sources:
   - url: https://github.com/Apicurio/apicurio-registry.git
-    branches: 2.6.x
+    branches: main
     start_path: docs
     edit_url: '{web_url}'
   - url: https://github.com/Apicurio/apicurio-registry-operator.git

docs/getting-started/master.adoc

@@ -27,5 +27,5 @@ include::assemblies/getting-started/assembly-all-registry-configurations.adoc[le
 include::assemblies/getting-started/assembly-managing-registry-artifacts-ui.adoc[leveloffset=+1]
 include::assemblies/getting-started/assembly-managing-registry-artifacts-api.adoc[leveloffset=+1]
 include::assemblies/getting-started/assembly-using-kafka-client-serdes.adoc[leveloffset=+1]
-include::assemblies/getting-started/assembly-using-the-registry-client.adoc[leveloffset=+1]
+include::assemblies/getting-started/assembly-using-the-registry-sdk.adoc[leveloffset=+1]
 include::assemblies/getting-started/assembly-registry-reference.adoc[leveloffset=+1]

docs/local-test-playbook.yml

@@ -36,6 +36,6 @@ asciidoc:
     managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console]
     managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API]
     managing-registry-artifacts-maven: link:assembly-managing-registry-artifacts-maven.html[Managing Apicurio Registry content using the Maven plug-in]
-    rest-client:  link:assembly-using-the-registry-client.html[Managing Apicurio Registry content using a Java client]
+    sdk:  link:assembly-using-the-registry-sdk.html[Managing Apicurio Registry content using an SDK]
     kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers in Java clients]
-    registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java clients]
+    registry-client-serdes-config: link:assembly-configuring-kafka-client-serdes.html[Configuring Kafka serializers/deserializers in Java applications]

docs/modules/ROOT/nav.adoc

@@ -7,7 +7,7 @@
 ** xref:getting-started/assembly-installing-registry-storage-openshift.adoc[]
 ** link:https://www.apicur.io/registry/docs/apicurio-registry-operator/1.0.0/index.html[Apicurio Registry Operator documentation]
 * Migration
-** xref:getting-started/assembly-migrating-registry-v1-v2.adoc[]
+** xref:getting-started/assembly-migrating-registry-v2-v3.adoc[]
 * Configuration
 ** xref:getting-started/assembly-configuring-registry-security.adoc[]
 ** xref:getting-started/assembly-configuring-the-registry.adoc[]

docs/modules/ROOT/pages/getting-started/assembly-artifact-reference.adoc

@@ -10,7 +10,9 @@ This chapter provides reference information on the supported artifact types, sta
 
 * xref:registry-artifact-types_{context}[]
 * xref:registry-artifact-states_{context}[]
+* xref:registry-group-metadata_{context}[]
 * xref:registry-artifact-metadata_{context}[]
+* xref:registry-artifact-version-metadata_{context}[]
 
 [role="_additional-resources"]
 .Additional resources
@@ -19,4 +21,6 @@ This chapter provides reference information on the supported artifact types, sta
 //INCLUDES
 include::{mod-loc}getting-started/ref-registry-artifact-types.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-artifact-states.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/ref-registry-group-metadata.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-artifact-metadata.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/ref-registry-artifact-version-metadata.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc

@@ -5,13 +5,11 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Configuring your {registry} deployment
 
 [role="_abstract"]
-This chapter explains how to set important configuration options for your {registry} deployment. This includes features such as the {registry} web console, logging, events, and health checks: 
+This chapter explains how to set important configuration options for your {registry} deployment. This includes features such as the {registry} web console, logging, and health checks:
 
 ifdef::apicurio-registry[]
 * xref:configuring-registry-ui_{context}[]
 endif::[]
-* xref:registry-logging_{context}[]
-* xref:registry-cloud-events_{context}[]
 * xref:configuring-liveness-readiness-probes_{context}[]
 * xref:registry-liveness-env-vars_{context}[]
 
@@ -21,7 +19,5 @@ NOTE: For a list of all available configuration options, see {registry-config-re
 ifdef::apicurio-registry[]
 include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1]
 endif::[]
-include::{mod-loc}getting-started/proc-configuring-registry-logging.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-configuring-registry-events.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-configuring-liveness-readiness-probes.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-liveness-env-vars.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-installing-registry-docker.adoc

@@ -14,7 +14,7 @@ This chapter explains how to install and run {registry} using Docker with the fo
 .Prerequisites
 * {registry-overview}
 
-NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on your storage option, for example, your Kafka or database cluster configuration, and on the number and type of artifacts stored in {registry}.
+NOTE: You can install more than one replica of {registry} depending on your environment. The number of replicas depends on your storage option, for example, your Kafka or database cluster configuration, and on the number and type of artifacts stored in {registry}.
 
 [role="_additional-resources"]
 .Additional resources

docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc

@@ -6,13 +6,10 @@ include::{mod-loc}shared/all-attributes.adoc[]
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
 [role="_abstract"]
-Client applications can use {registry} REST API operations to manage schema and API artifacts in {registry}, for example, in a CI/CD pipeline deployed in production. The Core Registry API v2 provides operations for artifacts, versions, metadata, and rules stored in {registry}. For detailed information, see the {registry-rest-api}.
+Client applications can use {registry} REST API operations to manage schema and API artifacts in {registry}, for example, in a CI/CD pipeline deployed in production. The Core Registry API v3 provides operations for artifacts, versions, metadata, and rules stored in {registry}. For detailed information, see the {registry-rest-api}.
 
-This chapter shows examples of how to use the Core Registry API v2 to perform the following tasks:
+This chapter shows examples of how to use the Core Registry API v3 to perform the following tasks:
 
-ifdef::rh-openshift-sr[]
-* xref:creating-access-token-for-registry-rest-api_{context}[]
-endif::[]
 * xref:managing-artifacts-using-rest-api_{context}[]
 * xref:managing-artifact-versions-using-rest-api_{context}[]
 * xref:managing-artifact-references-using-rest-api_{context}[]
@@ -26,9 +23,6 @@ endif::[]
 * link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
 
 //INCLUDES
-ifdef::rh-openshift-sr[]
-include::{mod-loc}getting-started/proc-creating-access-token-rest-api.adoc[leveloffset=+1]
-endif::[]
 include::{mod-loc}getting-started/proc-managing-artifacts-using-rest-api.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-managing-artifact-versions-using-rest-api.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-managing-artifact-references-using-rest-api.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc

@@ -14,7 +14,6 @@ endif::[]
 * xref:browsing-artifacts-using-console_{context}[]
 * xref:adding-artifacts-using-console_{context}[]
 * xref:configuring-rules-using-console_{context}[]
-* xref:generating-client-sdk-using-web-console_{context}[]
 * xref:changing-artifact-owner-using-console_{context}[]
 * xref:configuring-settings-using-console_{context}[]
 * xref:exporting-importing-using-web-console_{context}[]
@@ -27,7 +26,6 @@ endif::[]
 include::{mod-loc}getting-started/proc-browsing-artifacts-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-adding-artifacts-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-configuring-rules-using-console.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-generating-client-sdk-using-web-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-changing-artifact-owner-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-configuring-settings-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-exporting-importing-using-web-console.adoc[leveloffset=+1]

docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v1-v2.adoc → docs/modules/ROOT/pages/getting-started/assembly-migrating-registry-v2-v3.adoc

@@ -6,7 +6,7 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Migrating an existing {registry} deployment 
 
 [role="_abstract"]
-This chapter explains how to migrate an existing {registry} deployment from version {registry-v1} to version 2.x. 
+This chapter explains how to migrate an existing {registry} deployment from version 2.x to version 3.x.
 
 * xref:registry-migration_{context}[]
 * xref:migrating-registry-data_{context}[]

docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc

@@ -1,17 +1,17 @@
 // Metadata created by nebel
 include::{mod-loc}shared/all-attributes.adoc[]
 
-[id="using-the-registry-client_{context}"]
-= Managing {registry} content using a Java client
+[id="using-the-registry-sdk_{context}"]
+= Managing {registry} content using a SDK
 
 [role="_abstract"]
-You can write a {registry} Java client application and use it to manage artifacts stored in {registry}:
+You can write a {registry} client application (in Java, Typescript, Python, or Golang) and use it to manage artifacts stored in {registry}:
 
-* xref:registry-client-intro_{context}[]
-* xref:writing-registry-client_{context}[]
-* xref:registry-client-config_{context}[]
+* xref:registry-sdk-intro_{context}[]
+* xref:writing-registry-sdk_{context}[]
+* xref:registry-sdk-config_{context}[]
 
 //INCLUDES
-include::{mod-loc}getting-started/con-registry-client.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-writing-registry-client.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/ref-registry-client.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/con-registry-sdk.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/proc-writing-registry-sdk.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/ref-registry-sdk.adoc[leveloffset=+1]

docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc

@@ -7,12 +7,7 @@
 You can use {registry} with Apache Kafka Connect to stream data between Kafka and external systems. Using Kafka Connect, you can define connectors for different systems to move large volumes of data into and out of Kafka-based systems. 
 
 .{registry} and Kafka Connect architecture
-ifdef::apicurio-registry,rh-service-registry[]
 image::images/getting-started/registry-connect-architecture.png[Registry and Kafka Connect architecture]
-endif::[]
-ifdef::rh-openshift-sr[]
-image::../_images/introduction/registry-connect-architecture.png[Registry and Kafka Connect architecture]
-endif::[]
 
 {registry} provides the following features for Kafka Connect:
 

docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc

@@ -28,6 +28,51 @@ The items stored in {registry}, such as event schemas and API designs, are known
 
 When a schema or API design is added as an artifact in {registry}, client applications can then use that schema or API design to validate that the client messages conform to the correct data structure at runtime.
 
+Artifacts have metadata, both generated and editable.  Standard metadata for an artifact includes (but may not be limited to):
+
+=== Generated or immutable properties
+
+- groupId
+- artifactId
+- artifactType
+- createdOn
+- modifiedBy
+- modifiedOn
+
+=== Editable properties
+- name
+- description
+- labels
+- owner
+
+[discrete]
+== Artifact Versions
+Every artifact is composed of zero or more _artifact version_s.  Only artifact versions have actual
+content (as well as metadata).  These versions represent the evolution of the content of an artifact,
+and are immutable.  You can think of an Artifact as an ordered sequence of Versions, typically with
+the most recent version representing the "current" schema or API design content.
+
+
+Artifact Versions have metadata, both generated and editable.  Standard metadata for an artifact version includes (but may not be limited to):
+
+=== Generated or immutable properties
+
+- groupId
+- artifactId
+- version
+- globalId
+- contentId
+- owner
+- createdOn
+- modifiedBy
+- modifiedOn
+
+=== Editable properties
+- name
+- description
+- labels
+- state
+
 
 [discrete]
 == Groups of schemas and APIs
@@ -38,20 +83,23 @@ You can create optional artifact groups when adding your schemas and API designs
 
 Schema and API groups can contain multiple artifact types. For example, you could have Protobuf, Avro, JSON Schema, OpenAPI, or AsyncAPI artifacts all in the same group.
 
-You can create schema and API artifacts and groups using the {registry} web console, REST API, command line, Maven plug-in, or Java client application. The following simple example shows using the Core Registry REST API:
+Groups have metadata, both generated and editable.  Standard metadata for a group includes (but may not be limited to):
 
-[source,bash]
-----
-$ curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
-  -H "X-Registry-ArtifactId: share-price" \
-  --data '{"type":"record","name":"price","namespace":"com.example", \
-   "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
-  https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts
-----
+=== Generated or immutable properties
+
+- groupId
+- owner
+- createdOn
+- modifiedBy
+- modifiedOn
+
+=== Editable properties
+- description
+- labels
 
-This example creates an artifact group named `my-group` and adds an Avro schema with an artifact ID of `share-price`.
+You can create schema and API artifacts and groups using the {registry} web console, REST API, command line, Maven plug-in, or Java client application.
 
-NOTE: Specifying a group is optional when using the {registry} web console, and a `default` group is created automatically. When using the REST API or Maven plug-in, specify the `default` group in the API path if you do not want to create a unique group.
+NOTE: Specifying a group is optional when using the {registry} web console, and the `default` group is used automatically. When using the REST API or Maven plug-in, specify the `default` group in the API path if you do not want to create a unique group.
 
 [role="_additional-resources"]
 .Additional resources
@@ -121,12 +169,6 @@ You can manage artifact references using the {registry} core REST API, Maven plu
 .Additional resources
 
 * For details on managing artifact references, see:
-ifdef::apicurio-registry,rh-service-registry[]
 ** {managing-registry-artifacts-api}.
 ** {managing-registry-artifacts-maven}.
-endif::[]
-ifdef::rh-openshift-sr[]
-** {base-url}{manage-api-url-registry}[Managing Service Registry data using the Core Registry API].
-** {base-url}{manage-maven-plugin-url-registry}[Managing schemas and APIs using the Service Registry Maven plug-in].
-endif::[]
 * For a Java example, see the https://github.com/Apicurio/apicurio-registry/tree/main/examples/serdes-with-references[Apicurio Registry SerDes with references demonstration].