Docs: Build and serve the docs locally

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

For running local dev server you will only need to install stable version of Go and clone the repository:

git clone https://github.com/operator-framework/olm-docs/

For other tasks such as building production version of the site and linting you will also need to:

Install Node.js LTS
Install Docker or Podman

Build and Serve

You can build and serve your docs to http://localhost:1313/ with:

make serve

Any changes will be included in real time.

Running the Linting Script Locally

To run linting locally you will need to run the following command:

make lint

This assumes docker command is available. If you want to specify different engine such as podman:

make lint CONTAINER_ENGINE=podman

Behind this target, the hack/ci/link-check.sh script is responsible for running html-proofer that validates the generated HTML output.

Note: In the case you’re getting permission denied errors when reading from that mounted volume, set the following environment variable and re-run the linting script:

make lint CONTAINER_RUN_EXTRA_OPTIONS="--security-opt label=disable"

Docs: Channel Upgrade Graphs Legends

Mon, 01 Jan 0001 00:00:00 +0000

This document enumerates the legends for the graphs that depict channel upgrades throughout this site. Using the legends documented here can help to communicate channel upgrade graphs in a standardized way.

Legends

Diagram (e.g)	Description
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1):::head	Version of the operator which is the head of a channel different versions are available in
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1):::installed	Version of the operator currently installed on cluster
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1)	Operator bundle version which is installable
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; subgraph preview ID(v0.0.1) end	Operator bundle channel.
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; subgraph "preview (default)" ID(v0.0.1) --> ID2(v0.0.2) end	Default Operator bundle channel.
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) --> B(v0.0.4)	An upgrade path to replace one operator bundle version for another using the `olm.channel` `replaces` field. More info: here.
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) x--x \|v0.0.2,v0.0.3\| B(v0.0.4)	An upgrade path to skip versions in the upgrade path using the `olm.channel` `skips` field. More info: here.
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; C(v2.0.3) o--o \|>= 2.0.4 < 3.0.0\| D(v3.0.1)	An upgrade path to skip a range of operator bundle versions using the `olm.channel` `skipRange` field. More info: here.
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) -.-> B(v0.0.4)	Represent the same replace method describe above but for a future scenario
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) x-.-x \|v0.0.2,v0.0.3\| B(v0.0.4)	Represent the same skips method describe above but for a future scenario
flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; C(v2.0.3) o-.-o \|>= 2.0.4 < 3.0.0\| D(v3.0.1)	Represent the same skipRange method describe above but for a future scenario
flowchart TB classDef head fill:#ff668d; classDef installed fill:#34ebba; E(v0.0.2 \n fa:fa-tag label=value)	catalog image label with its value for an operator bundle version. (eg.`LABEL com.vendor.release.versions:=v4.7`)

Creating graphs

The graphs are done programmatically via mermaid. You can use its online editor to work with them and check the following examples.

Check the following example:

flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; subgraph stable A(v0.0.1):::installed --> B(v0.0.2) B(v0.0.2) x--x |v0.0.3,v0.0.4| C(v0.0.5 \n fa:fa-tag 4.6):::head C -.-> E(v0.0.6 \n fa:fa-tag 4.6) end

Now, check the code used to generate this example:

flowchart TB
 classDef head fill:#ffbfcf;
 classDef installed fill:#34ebba;

 subgraph stable
 A(v0.0.1):::installed --> B(v0.0.2)
 B(v0.0.2) x--x |v0.0.3,v0.0.4| C(v0.0.5 \n fa:fa-tag 4.6):::head
 C -.-> E(v0.0.6 \n fa:fa-tag 4.6)
 end

Usage code

Note that, the graphs requires starts with:

flowchart TB
 classDef head fill:#ffbfcf;
 classDef installed fill:#34ebba;

Following the code semantic with examples which ought to be used to create the Upgrade Graphs Diagrams.

Description	Code	Examples
head bundle	`ID(<bundle tag>):::head`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1):::head
installed bundle	`ID(<bundle tag>):::installed`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1):::installed
installable bundle	`ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; ID(v0.0.1)
channel	`subgraph <channel name> end`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; subgraph preview ID(v0.0.1) end
default channel	`subgraph "<channel name> (default)" end`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; subgraph "preview (default)" ID(v0.0.1) --> ID2(v0.0.2) end
replaces	`ID(<bundle tag>) --> ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) --> B(v0.0.4)
skips	`ID(<bundle tag>) x--x \| <versions that should be skipped> \| ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) x--x \|v0.0.2,v0.0.3\| B(v0.0.4)
skipRange	`ID<bundle tag>) o--o \| <range> \| ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; C(v2.0.3) o--o \|>= 2.0.4 < 3.0.0\| D(v3.0.1)
future replaces	`ID(<bundle tag>) -.-> ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) -.-> B(v0.0.4)
future skips	`ID(<bundle tag>) x-.-x \| <versions that should be skipped> \| ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; A(v0.0.1) x-.-x \|v0.0.2,v0.0.3\| B(v0.0.4)
future skipRange	`ID<bundle tag>) o-.-o \| <range> \| ID(<bundle tag>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; C(v2.0.3) o-.-o \|>= 2.0.4 < 3.0.0\| D(v3.0.1)
Index image label	`ID(<bundle tag> \n fa:fa-tag <label>=<value>)`	flowchart TB classDef head fill:#ffbfcf; classDef installed fill:#34ebba; E(v0.0.2 \n fa:fa-tag label=value)

Operator Lifecycle Manager – Contribution Guidelines