Add component library documentation

* Function comments in library
* Page in component documentation

Makefile.vars.mk

@@ -22,7 +22,7 @@ YAMLLINT_DOCKER ?= $(DOCKER_CMD) $(DOCKER_ARGS) $(root_volume) $(YAMLLINT_IMAGE)
 VALE_CMD  ?= $(DOCKER_CMD) $(DOCKER_ARGS) $(root_volume) --volume "$${PWD}"/docs/modules:/pages vshn/vale:2.1.1
 VALE_ARGS ?= --minAlertLevel=error --config=/pages/ROOT/pages/.vale.ini /pages
 
-ANTORA_PREVIEW_CMD ?= $(DOCKER_CMD) run --rm --publish 2020:2020 --volume "${PWD}":/antora vshn/antora-preview:2.3.3 --style=syn --antora=docs
+ANTORA_PREVIEW_CMD ?= $(DOCKER_CMD) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:2.3.7 --style=syn --antora=docs
 
 COMMODORE_CMD  ?= $(DOCKER_CMD) $(DOCKER_ARGS) $(root_volume) projectsyn/commodore:latest component compile . $(commodore_args)
 JB_CMD         ?= $(DOCKER_CMD) $(DOCKER_ARGS) --entrypoint /usr/local/bin/jb projectsyn/commodore:latest install

docs/modules/ROOT/pages/how-tos/getting-started.adoc

@@ -77,6 +77,8 @@ local operatorlib = import 'lib/openshift4-operators.libsonnet';
 Use the same value as you've selected for `${INSTANCE}` in the 3rd step.
 <2> The name of the operator to install
 <3> The update channel for the subscription
++
+TIP: See the xref:references/component-library.adoc[component library] reference documentation for full documentation of the functions provided by the library.
 
 . Compile the catalog locally to check your changes
 +

docs/modules/ROOT/pages/references/component-library.adoc

@@ -0,0 +1,85 @@
+= Component library
+
+The component provides a component library to make creating Operator Lifecycle Manager (OLM) resources easier.
+This page documents the provided library functions.
+
+== `OperatorGroup`
+
+This function provides a wrapper to create `operatorgroups.operators.coreos.com` resources.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`name`:: The name of the resource. Used as `.metadata.name`.
+--
+
+== `validateInstance`
+
+This function takes an instance name and validates it against the supported instance names.
+Optionally the instance name is also validated against the instances which are present in the cluster catalog.
+
+If the validation is successful, the function returns the instance name unmodified.
+Otherwise it throws an error during catalog compilation.
+
+--
+.Arguments
+`instance`:: The instance name to validate.
+`checkTargets`:: Whether to validate the instance against configured component instances.
+`checkSource`:: An arbitrary string included in the error output when checking against configured component instances.
+This is included in the error in the following sentence `"Unknown instance '<instance>' for <checkSource>"`.
+--
+
+== `managedSubscription`
+
+This function creates a `subscriptions.operators.coreos.com` resource in a namespace managed by this component.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`instance`:: Name of the component instance in which to create the subscription
+`name`:: Name of the operator to install.
+Used as `.metadata.name` and `.spec.name` of the resulting `Subscription` object.
+`channel`:: The channel for the subscription.
+`source`:: The source (`CatalogSource`) for the operator.
+Defaults to `parameters.<instance>.defaultSource`.
+This argument can be omitted.
+`sourceNamespace`:: The namespace holding the `CatalogSource`.
+Defaults to `parameters.<instance>.defaultSourceNamespace`.
+This argument can be omitted.
+`installPlanApproval`:: How to manage subscription updates.
+Valid options are `Automatic` and `Manual`.
+Defaults to `parameters.<instance>.defaultInstallPlanApproval`.
+This argument can be omitted.
+--
+
+Arguments `source`, `sourceNamespace` and `installPlanApproval` are optional and default to component instance parameters `defaultSource`, `defaultSourceNamespace` and `defaultInstallPlanApproval`.
+
+== `namespacedSubscription`
+
+This function creates a `subscriptions.operators.coreos.com` resource in an arbitrary namespace.
+When using this function, the caller is responsible to ensure that an `OperatorGroup` resource exists in the target namespace.
+
+The result of this function can be used in the same way as resources created by `kube.libjsonnet`.
+
+--
+.Arguments
+`instance`:: Name of the component instance in which to create the subscription
+`name`:: Name of the operator to install.
+Used as `.metadata.name` and `.spec.name` of the resulting `Subscription` object.
+`channel`:: The channel for the subscription.
+`source`:: The source (`CatalogSource`) for the operator.
+Defaults to `parameters.<instance>.defaultSource`.
+This argument can be omitted.
+`sourceNamespace`:: The namespace holding the `CatalogSource`.
+Defaults to `parameters.<instance>.defaultSourceNamespace`.
+This argument can be omitted.
+`installPlanApproval`:: How to manage subscription updates.
+Valid options are `Automatic` and `Manual`.
+Defaults to `parameters.<instance>.defaultInstallPlanApproval`.
+This argument can be omitted.
+--
+
+Arguments `source`, `sourceNamespace` and `installPlanApproval` are optional and default to component instance parameters `defaultSource`, `defaultSourceNamespace` and `defaultInstallPlanApproval`.
+

docs/modules/ROOT/partials/nav.adoc

@@ -1,3 +1,8 @@
 * xref:index.adoc[Home]
+
+.How-tos
 * xref:how-tos/getting-started.adoc[Getting started]
+
+.Reference
+* xref:references/component-library.adoc[Component library]
 * xref:references/parameters.adoc[Parameters]

lib/openshift4-operators.libsonnet

@@ -15,6 +15,22 @@ local instanceParams(instance) =
 
 local apigroup = 'operators.coreos.com';
 
+/**
+ * \brief Validate instance
+ *
+ * This function takes an instance name and validates it against the supported
+ * instance names and optionally against the instances present in the cluster
+ * catalog.
+ *
+ * \arg instance The instance to validate
+ * \arg checkTargets Whether to validate the instance against configured
+ * component instances
+ * \arg checkSource Free-form string included in the error output when
+ * checking against configured component instances. This is included in the
+ * error as "Unknown instance '<instance>' for <checkSource>".
+ *
+ * \returns `instance` if it validates. Throws an assertion error otherwise.
+ */
 local validateInstance(instance, checkTargets=false, checkSource='') =
   local supported_instances = std.set([
     'openshift-operators',
@@ -51,9 +67,41 @@ local subscription(name) =
     },
   };
 
+/**
+ * \brief Wrapper to create `OperatorGroup` resources
+ *
+ * The result of this function can be used in the same way as resources
+ * created by `kube.libjsonnet`.
+ *
+ * \arg name Value for `.metadata.name` of the resource
+ *
+ * \returns an `OperatorGroup` resource
+ */
 local OperatorGroup(name) =
   kube._Object(apigroup + '/v1', 'OperatorGroup', name);
 
+/**
+ * \brief Create a cluster-scoped subscription object in a namespace managed
+ * by this component
+ *
+ * The result of this function can be used in the same way as resources
+ * created by `kube.libjsonnet`.
+ *
+ * \arg instance Name of the component instance in which to create the
+ * subscription
+ * \arg name Name of the operator to install. Used as `.metadata.name` and
+ * `.spec.name` of the resulting `Subscription` object.
+ * \arg channel The channel for the subscription.
+ * \arg source The source (`CatalogSource`) for the operator. Defaults to
+ * `parameters.<instance>.defaultSource`.
+ * \arg sourceNamespace The namespace holding the `CatalogSource`. Defaults to
+ * `parameters.<instance>.defaultSourceNamespace`.
+ * \arg installPlanApproval How to manage subscription updates. Valid options
+ * are `Automatic` and `Manual`. Defaults to
+ * `parameters.<instance>.defaultInstallPlanApproval`.
+ *
+ * \returns a preconfigured `Subscription` resource
+ */
 local managedSubscription =
   function(
     instance,
@@ -77,6 +125,26 @@ local managedSubscription =
       installPlanApproval
     );
 
+/**
+ * \brief Create a subscription object in an arbitrary namespace
+ *
+ * The result of this function can be used in the same way as resources
+ * created by `kube.libjsonnet`.
+ *
+ * \arg namespace The namespace in which to create the resource
+ * \arg name Name of the operator to install. Used as `.metadata.name` and
+ * `.spec.name` of the resulting `Subscription` object.
+ * \arg channel The channel for the subscription.
+ * \arg source The source (`CatalogSource`) for the operator. Defaults to
+ * `parameters.<instance>.defaultSource`.
+ * \arg sourceNamespace The namespace holding the `CatalogSource`. Defaults to
+ * `parameters.<instance>.defaultSourceNamespace`.
+ * \arg installPlanApproval How to manage subscription updates. Valid options
+ * are `Automatic` and `Manual`. Defaults to
+ * `parameters.<instance>.defaultInstallPlanApproval`.
+ *
+ * \returns a preconfigured `Subscription` resource
+ */
 local namespacedSubscription =
   function(
     namespace,