[Fix #601] Fix SonataFlow docs issues found during SME reviews and consultations

serverlessworkflow/antora.yml

@@ -27,24 +27,32 @@ nav:
 - "modules/ROOT/nav.adoc"
 asciidoc:
   attributes:
-    # for product names
-    #in Downstream product_name: OpenShift Serverless Logic
+    # 
+    # Names, labels and similar
+    #
     product_name: SonataFlow
-    # upstream: empty
-    #kogito_version_redhat: 1.24.0.Final-redhat-00001
-    kogito_version_redhat: ""
-    # same for upstream and downstream while the operator is community only
     operator_name: SonataFlow Operator
     operator_installation_namespace: sonataflow-operator-system
-    # upstream: io.quarkus.platform
-    #quarkus_platform: com.redhat.quarkus.platform
     quarkus_platform: io.quarkus.platform
-    # upstream: kogito-quarkus-serverless-workflow
-    # kogito_sw_ga: org.kie.kogito:kogito-quarkus-serverless-workflow
     kogito_sw_ga: kogito-quarkus-serverless-workflow
-    # downstream: 2.7.6.Final-redhat-00006
+    data_index_ref: Data Index
+    workflow_instance: workflow instance
+    workflow_instances: workflow instances
+    operator_openshift_keyword: sonataflow
+    operator_openshift_catalog: sonataflow-operator
+    operator_k8s_keyword: sonataflow
+    operator_k8s_subscription: my-sonataflow-operator
+    kogito_devservices_imagename: quay.io/kiegroup/kogito-data-index-ephemeral-nightly
+    sonataflow_devmode_imagename: quay.io/kiegroup/kogito-swf-devmode-nightly
+    sonataflow_builder_imagename: quay.io/kiegroup/kogito-swf-builder-nightly
+    sonataflow_devmode_devui_url: /q/dev/org.kie.kogito.kogito-quarkus-serverless-workflow-devui/
+    serverless_logic_web_tools_name: Serverless Logic Web Tools
+    serverless_workflow_vscode_extension_name: KIE Serverless Workflow Editor
+
+    #
+    #  Versions 
+    #
     quarkus_version: 3.2.9.Final
-    # downstream: 2.7.6.Final-redhat-00006 (might be different to the quarkus_version)
     quarkus_platform_version: 3.2.9.Final
     java_min_version: 17+
     maven_min_version: 3.9.3
@@ -56,20 +64,17 @@ asciidoc:
     docker_min_version: 20.10.7
     docker_compose_min_version: 1.27.2
     kubernetes_version: 1.26
-    openshift_version_min: 4.10
+    openshift_version_min: 4.12
     openshift_version_max: 4.15
     knative_version: 1.13
     knative_serving_version: 1.13
     knative_eventing_version: 1.13
     # only used in downstream
     operator_version: main
-    # after TP1, change to Serverless Logic
-    operator_openshift_keyword: sonataflow
-    operator_openshift_catalog: sonataflow-operator
-    operator_k8s_keyword: sonataflow
-    operator_k8s_subscription: my-sonataflow-operator
-    kogito_devservices_imagename: registry.redhat.io/openshift-serverless-1-tech-preview/logic-data-index-ephemeral-rhel8
-    sonataflow_devmode_imagename: quay.io/kiegroup/kogito-swf-devmode
+
+    #
+    # URLs 
+    #
     kogito_examples_repository_url: https://github.com/apache/incubator-kie-kogito-examples
     kogito_sw_examples_url: https://github.com/apache/incubator-kie-kogito-examples/tree/main/serverless-workflow-examples
     kogito_sw_operator_examples_url: https://github.com/apache/incubator-kie-kogito-examples/tree/main/serverless-operator-examples
@@ -85,7 +90,7 @@ asciidoc:
     open_api_spec_url: https://spec.openapis.org/oas/v3.1.0.html
     open_api_swagger_spec_url: https://swagger.io/docs/specification
     quarkus_openapi_gen_url: https://github.com/quarkiverse/quarkus-openapi-generator
-    kie_tools_releases_page_url: https://github.com/kiegroup/kie-tools/releases
+    kie_tools_releases_page_url: https://github.com/apache/incubator-kie-tools/releases
     quarkus_guides_base_url: https://quarkus.io/guides
     quarkus_guides_kafka_url: https://quarkus.io/guides/kafka
     quarkus_guides_config_reference_url: https://quarkus.io/guides/config-reference
@@ -109,15 +114,15 @@ asciidoc:
     pnpm_install_url: https://pnpm.io/installation
     golang_install_url: https://go.dev/doc/install
     serverless_logic_web_tools_url: https://start.kubesmarts.org/
+    swf_executor_core_maven_repo_url: https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-core
     github_tokens_url: https://github.com/settings/tokens
     openshift_developer_sandbox_url: https://developers.redhat.com/developer-sandbox
     openshift_application_data_services_service_account_url: https://console.redhat.com/application-services/service-accounts
     openshift_application_data_services_service_registry_url: https://console.redhat.com/application-services/service-registry
     openshift_application_data_services_apache_kafka_url: https://console.redhat.com/application-services/streams/kafkas
     camel_url: https://camel.apache.org/
-    serverless_logic_web_tools_name: Serverless Logic Web Tools
     # must align this version
-    camel_extensions_url: https://camel.apache.org/camel-quarkus/2.14.x/reference/extensions
+    camel_extensions_url: https://camel.apache.org/camel-quarkus/3.2.x/reference/extensions
     kaoto_url: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-kaoto
     minikube_url: https://minikube.sigs.k8s.io
     kogito_serverless_operator_url: https://github.com/apache/incubator-kie-kogito-serverless-operator/
@@ -126,13 +131,10 @@ asciidoc:
     ocp_knative_serving_url: https://docs.openshift.com/container-platform/4.12/serverless/install/installing-knative-serving.html
     ocp_knative_eventing_url: https://docs.openshift.com/container-platform/4.12/serverless/install/installing-knative-eventing.html
     ocp_kn_cli_url: https://docs.openshift.com/container-platform/4.12/serverless/install/installing-kn.html
-    serverless_workflow_vscode_extension_name: KIE Serverless Workflow Editor
-    # xreferences to documents within the documentation.
+
+    #
+    # xreferences to documents within the documentation
+    #
     data_index_xref: xref:data-index/data-index-core-concepts.adoc
     job_service_xref: xref:job-services/core-concepts.adoc
-    # string unication references
-    data_index_ref: Data Index
-    workflow_instance: workflow instance
-    workflow_instances: workflow instances
-    sonataflow_devmode_devui_url: /q/dev/org.kie.kogito.kogito-quarkus-serverless-workflow-devui/
-    swf_executor_core_maven_repo: https://mvnrepository.com/artifact/org.kie.kogito/kogito-serverless-workflow-executor-core
+

serverlessworkflow/modules/ROOT/nav.adoc

@@ -79,6 +79,7 @@
 *** xref:cloud/operator/building-custom-images.adoc[Building Custom Images]
 *** xref:cloud/operator/customize-podspec.adoc[Custom Workflow PodSpec]
 *** xref:cloud/operator/service-discovery.adoc[Service Discovery]
+*** xref:cloud/operator/using-persistence.adoc[Using Persistence]
 *** xref:cloud/operator/configuring-knative-eventing-resources.adoc[Knative Eventing]
 *** xref:cloud/operator/known-issues.adoc[Roadmap and Known Issues]
 * Integrations

serverlessworkflow/modules/ROOT/pages/getting-started/create-your-first-workflow-service-with-kn-cli-and-vscode.adoc

@@ -65,7 +65,7 @@ Minikube::
 minikube service hello --namespace my-sf-application --url
 ----
 * Use this URL to access your workflow instances using the Developer UI
-** <RETURNED_URL>{sonataflow_devmode_devui_url}/workflowInstances
+** <RETURNED_URL>{sonataflow_devmode_devui_url}workflowInstances
 --
 Kind::
 +

serverlessworkflow/modules/ROOT/pages/getting-started/java-embedded-workflows.adoc

@@ -9,7 +9,7 @@ The workflow definition to be executed can be read from a `.json` or `.yaml` fil
 [[embedded-file-quick-start]]
 == Hello world (using existing definition file)
 
-The first step is to set up an empty Maven project that includes link:{swf_executor_core_maven_repo}[Workflow executor core] dependency.
+The first step is to set up an empty Maven project that includes link:{swf_executor_core_maven_repo_url}[Workflow executor core] dependency.
 
 This guide also uses [slf4j dependency](https://mvnrepository.com/artifact/org.slf4j/slf4j-simple) to avoid using `System.out.println`
 

serverlessworkflow/modules/ROOT/pages/getting-started/learning-environment.adoc

@@ -7,7 +7,7 @@
 If you are new to {product_name} we recommend a few starting points to get up to speed with the technology and what it has to offer. 
 
 * Read the xref:core/cncf-serverless-workflow-specification-support.adoc[serverless workflow specification and what is supported]. 
-* Try our link:{serverless_logic_web_tools_url}/sample-catalog?category=serverless-workflow[{serverless_logic_web_tools_name} samples]. 
+* Try our link:{serverless_logic_web_tools_url}#/sample-catalog?category=serverless-workflow[{serverless_logic_web_tools_name} samples]. 
 
 Once familiar with the specification and samples, navigate to xref:getting-started/preparing-environment.adoc[] guide to complete the necesarry setup of your environment. After that, you should be ready to create your first {product_name} application.
 

serverlessworkflow/modules/ROOT/pages/integrations/core-concepts.adoc

@@ -1,3 +1,12 @@
 = Introduction
 
-This guides describes the possibilities of workflow services integrations.
+This guides describes the possibilities of workflow services integrations.
+Currently we showcase these in advanced development guides. See additional resources.
+
+
+== Additional resources
+
+* xref:use-cases/advanced-developer-use-cases/integrations/camel-routes-integration.adoc[]
+* xref:use-cases/advanced-developer-use-cases/integrations/custom-functions-knative.adoc[]
+* xref:use-cases/advanced-developer-use-cases/integrations/expose-metrics-to-prometheus.adoc[]
+* xref:use-cases/advanced-developer-use-cases/integrations/serverless-dashboard-with-runtime-data.adoc[]