#1287 Templating renderables documentation

ontrack-docs/src/docs/asciidoc/appendix-templating.adoc

@@ -57,8 +57,12 @@ To see the list of possible events and their contexts, see <<appendix-events>>.
 
 The next sections list the available sources, functions and filters.
 
+There are also special objects, known as _templating renderable_, which are specific to some contexts, like <<auto-versioning>> or <<workflows>>.
+
 include::templating/sources/index.adoc[]
 
 include::templating/functions/index.adoc[]
 
 include::templating/filters/index.adoc[]
+
+include::templating/renderables/index.adoc[]

ontrack-docs/src/docs/asciidoc/templating/renderables/index.adoc

@@ -0,0 +1,8 @@
+[[appendix-templating-renderable-index]]
+==== List of special templating objects
+
+* <<templating-renderable-av,Auto-versioning context (av)>>
+* <<templating-renderable-workflow,Information about the workflow (workflow)>>
+
+include::templating-renderable-av.adoc[]
+include::templating-renderable-workflow.adoc[]

ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-av.adoc

@@ -0,0 +1,23 @@
+[[templating-renderable-av]]
+==== Auto-versioning context (av)
+
+The `av` context can be used in templates in the PR title & body templates, in order to access information about the auto-versioning request.
+
+Context: Auto-versioning
+
+Available fields:
+
+* `changelog`: Changelog for the project & version being updated
+
+** **allQualifiers** - Boolean - required - Loop over all qualifiers for the last level of `dependencies`, including the default one. Qualifiers at `dependencies` take precedence.
+
+** **commitsOption** - NONE, OPTIONAL, ALWAYS - required - Defines how to render commits for a change log
+
+** **defaultQualifierFallback** - Boolean - required - If a qualifier has no previous link, uses the default qualifier (empty) qualifier.
+
+** **dependencies** - List - required - Comma-separated list of project links to follow one by one for a get deep change log. Each item in the list is either a project name, or a project name and qualifier separated by a colon (:).
+
+** **empty** - String - required - String to use to render an empty or non existent change log
+
+** **title** - Boolean - required - Include a title for the change log
+

ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflow.adoc

@@ -0,0 +1,13 @@
+[[templating-renderable-workflow]]
+==== Information about the workflow (workflow)
+
+The `workflow` context is used to access information about the nodes of the workflow, in notifications or other templates rendered in the context of the workflow execution.
+
+Context: Workflow
+
+Available fields:
+
+* `<node id>`: Getting information about a node in the current workflow
+
+** **path** - String - required - JSON path to the data to render
+

ontrack-extension-auto-versioning/src/main/java/net/nemerosa/ontrack/extension/av/processing/AutoVersioningOrderTemplatingRenderableDoc.kt

@@ -0,0 +1,29 @@
+package net.nemerosa.ontrack.extension.av.processing
+
+import net.nemerosa.ontrack.extension.scm.changelog.ChangeLogTemplatingServiceConfig
+import net.nemerosa.ontrack.model.annotations.APIDescription
+import net.nemerosa.ontrack.model.templating.TemplatingRenderableDoc
+import net.nemerosa.ontrack.model.templating.TemplatingRenderableDocField
+import org.springframework.stereotype.Component
+
+/**
+ * Documentation for AutoVersioningOrderTemplatingRenderable.
+ */
+@Component
+@APIDescription("The `av` context can be used in templates in the PR title & body templates, in order to access information about the auto-versioning request.")
+class AutoVersioningOrderTemplatingRenderableDoc : TemplatingRenderableDoc {
+
+    override val id: String = "av"
+
+    override val displayName: String = "Auto-versioning context"
+
+    override val contextName: String = "Auto-versioning"
+
+    override val fields: List<TemplatingRenderableDocField> = listOf(
+        TemplatingRenderableDocField(
+            name = "changelog",
+            description = "Changelog for the project & version being updated",
+            config = ChangeLogTemplatingServiceConfig::class,
+        )
+    )
+}

ontrack-extension-workflows/src/main/java/net/nemerosa/ontrack/extension/workflows/templating/WorkflowTemplatingRenderableDoc.kt

@@ -0,0 +1,25 @@
+package net.nemerosa.ontrack.extension.workflows.templating
+
+import net.nemerosa.ontrack.model.annotations.APIDescription
+import net.nemerosa.ontrack.model.templating.TemplatingRenderableDoc
+import net.nemerosa.ontrack.model.templating.TemplatingRenderableDocField
+import org.springframework.stereotype.Component
+
+@Component
+@APIDescription("The `workflow` context is used to access information about the nodes of the workflow, in notifications or other templates rendered in the context of the workflow execution.")
+class WorkflowTemplatingRenderableDoc : TemplatingRenderableDoc {
+
+    override val id: String = "workflow"
+
+    override val displayName: String = "Information about the workflow"
+
+    override val contextName: String = "Workflow"
+
+    override val fields: List<TemplatingRenderableDocField> = listOf(
+        TemplatingRenderableDocField(
+            name = "<node id>",
+            description = "Getting information about a node in the current workflow",
+            config = WorkflowTemplatingRenderableParameters::class,
+        )
+    )
+}

ontrack-model/src/main/java/net/nemerosa/ontrack/model/templating/TemplatingRenderableDoc.kt

@@ -0,0 +1,29 @@
+package net.nemerosa.ontrack.model.templating
+
+/**
+ * This interface is used to create beans which act as documentation
+ * for instances of [TemplatingRenderable] object.
+ */
+interface TemplatingRenderableDoc {
+
+    /**
+     * This ID is used to identify the renderable into a context
+     */
+    val id: String
+
+    /**
+     * Display name of the renderable (used for documentation only)
+     */
+    val displayName: String
+
+    /**
+     * Where this renderable can be used
+     */
+    val contextName: String
+
+    /**
+     * Supported fields
+     */
+    val fields: List<TemplatingRenderableDocField>
+
+}

ontrack-model/src/main/java/net/nemerosa/ontrack/model/templating/TemplatingRenderableDocField.kt

@@ -0,0 +1,16 @@
+package net.nemerosa.ontrack.model.templating
+
+import kotlin.reflect.KClass
+
+/**
+ * Representation of a field in a [TemplatingRenderable].
+ *
+ * @property name Name of the field
+ * @property description Description of the field
+ * @property config Class of the field (for the documentation)
+ */
+data class TemplatingRenderableDocField(
+    val name: String,
+    val description: String,
+    val config: KClass<*>,
+)

ontrack-ui/src/test/java/net/nemerosa/ontrack/boot/docs/DocumentationGenerationIT.kt

@@ -5,10 +5,12 @@ import net.nemerosa.ontrack.extension.notifications.channels.NotificationChannel
 import net.nemerosa.ontrack.extension.workflows.execution.WorkflowNodeExecutor
 import net.nemerosa.ontrack.it.AbstractDSLTestSupport
 import net.nemerosa.ontrack.model.annotations.getAPITypeDescription
+import net.nemerosa.ontrack.model.annotations.getAPITypeName
 import net.nemerosa.ontrack.model.docs.*
 import net.nemerosa.ontrack.model.events.*
 import net.nemerosa.ontrack.model.templating.TemplatingFilter
 import net.nemerosa.ontrack.model.templating.TemplatingFunction
+import net.nemerosa.ontrack.model.templating.TemplatingRenderableDoc
 import net.nemerosa.ontrack.model.templating.TemplatingSource
 import org.junit.jupiter.api.Disabled
 import org.junit.jupiter.api.Test
@@ -42,6 +44,64 @@ class DocumentationGenerationIT : AbstractDocumentationGenerationTestSupport() {
     @Autowired
     private lateinit var workflowNodeExecutors: List<WorkflowNodeExecutor>
 
+    @Autowired
+    private lateinit var templatingRenderableDocs: List<TemplatingRenderableDoc>
+
+    @Test
+    fun `Templating renderables`() {
+
+        fun getTRDFileId(trd: TemplatingRenderableDoc): String =
+            "templating-renderable-${trd.id}"
+
+        fun getTRDTitle(trd: TemplatingRenderableDoc): String =
+            "${trd.displayName} (${trd.id})"
+
+        fun generateTRD(directoryContext: DirectoryContext, trd: TemplatingRenderableDoc) {
+            val description = getAPITypeDescription(trd::class)
+            val example = getDocumentationExampleCode(trd::class)
+
+            val fileId = getTRDFileId(trd)
+
+            directoryContext.writeFile(
+                fileId = fileId,
+                level = 4,
+                title = getTRDTitle(trd),
+                header = description,
+                fields = emptyList(),
+                example = example,
+                extendedConfig = { s ->
+                    // Context
+                    s.append("Context: ${trd.contextName}\n\n")
+                    // Fields
+                    s.append("Available fields:\n\n")
+                    trd.fields.forEach { field ->
+                        s.append("* `${field.name}`: ${field.description}\n\n")
+                        val list = getFieldsDocumentation(field.config)
+                        directoryContext.writeFields(s, list, level = 2)
+                    }
+                },
+            )
+        }
+
+        withDirectory("templating/renderables") {
+
+            writeIndex(
+                fileId = "appendix-templating-renderable-index",
+                level = 4,
+                title = "List of special templating objects",
+                items = templatingRenderableDocs.associate { trd ->
+                    getTRDFileId(trd) to getTRDTitle(trd)
+                }
+            )
+
+            templatingRenderableDocs.forEach { trd ->
+                generateTRD(this, trd)
+            }
+
+        }
+
+    }
+
     @Test
     fun `Workflow node executors`() {