Doc: Fix some rendering errors, use cayman theme on gh.io

Change-Id: I56a6b44eb83dfed15c03e938d30981428a8daeb5

README.md

@@ -62,15 +62,15 @@ The current project status is: **Alpha - NOT PRODUCTION READY**
 
 ## Getting Started
 
-* [Installing the Operator ](doc/operator/getting_started.md)
-* [Deploying Zuul and dependencies with SF-Operator](doc/deployment/getting_started.md)
+* [Installing the Operator ](https://softwarefactory-project.github.io/sf-operator/operator/getting_started.html)
+* [Deploying Zuul and dependencies with SF-Operator](https://softwarefactory-project.github.io/sf-operator/deployment/getting_started.html)
 
 ## Documentation
 
-* [Operator documentation](doc/operator/index.md): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle.
-* [Deployment documentation](doc/deployment/index.md): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator.
-* [Developer documentation](doc/developer/index.md): this documentation describes how to set up a development and testing environment to develop the SF-Operator.
-* [CLI refererence](doc/cli/index.md)
+* [Operator documentation](https://softwarefactory-project.github.io/sf-operator/operator/): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle.
+* [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator.
+* [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator.
+* [CLI refererence](https://softwarefactory-project.github.io/sf-operator/cli/)
 ## Getting Help
 
 Should you have any questions or feedback concerning the SF-Operator, you can:
@@ -81,8 +81,8 @@ Should you have any questions or feedback concerning the SF-Operator, you can:
 
 ## Contributing
 
-Refer to [CONTRIBUTING.md](CONTRIBUTING.md).
+Refer to [CONTRIBUTING.md](https://github.com/softwarefactory-project/sf-operator/blob/master/CONTRIBUTING.md).
 
 ## Licence
 
-Sf-operator is distributed under the [Apache License](LICENSE).
+Sf-operator is distributed under the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.txt).

doc/README.md

@@ -0,0 +1 @@
+../README.md

doc/_config.yml

@@ -0,0 +1,4 @@
+theme: cayman
+source: doc/
+exclude:
+  - adr/adr-template.md

doc/adr/index.md

@@ -2,6 +2,20 @@
 
 This directory contains decision records for sf-operator.
 
-For new ADRs, please use [adr-template.md](adr-template.md) as basis.
+For new ADRs, please use [adr-template.md](adr-template.md) as a boilerplate.
 More information on MADR is available at <https://adr.github.io/madr/>.
 General information about architectural decision records is available at <https://adr.github.io/>.
+
+## Table of Contents
+
+1. [Use Markdown for ADRs](./0000-use-markdown-any-decision-records.md)
+1. [Operator Configuration](./0001-operator-config.md)
+1. [Zuul System config](./0002-zuul-system-config.md)
+1. [Config update workflow - base system](./0003-config-update.md)
+1. [Expose main.yaml to Zuul scheduler](./0004-zuul-main.md)
+1. [Command line tool to setup an manage sf-operator deployment](./0005-ops-tooling.md)
+1. [Operator and Operand Metrics Collection](./0006-monitoring.md)
+1. [Edge certificates management](./0007-edge-cert.md)
+1. [Config check and update jobs implementation](./0008-config-jobs.md)
+1. [Database Agnosticity for SF Deployments](./0009-database-agnosticity.md)
+1. [Usage of the upstream zuul-operator](./0010-zuul-operator-usage.md)

doc/cli/index.md

@@ -77,6 +77,7 @@ sfconfig operator delete [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -a, --all   |      boolean           | executes all options in sequence|-|
@@ -121,6 +122,7 @@ sfconfig sf delete [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -a, --all  |  boolean  |  executes --delete and --remove options in sequence|-|
@@ -167,6 +169,7 @@ sfconfig nodepool-providers-secrets [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -d, --dump  |       boolean     |    Dump the providers secrets from the sf namespace to the local config (exclusive with '-u')|-|
@@ -191,6 +194,7 @@ sfconfig zuul create-auth-token [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -x, --expires-in| int32 |  The lifespan in seconds of the token. | 15 minutes (900s)|
@@ -224,6 +228,7 @@ sfconfig bootstrap-tenant-config-repo [...]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |      --connection |string  | Name of the connection or a source|-|
@@ -242,6 +247,7 @@ sfconfig gerrit [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |      --deploy |  boolean   |  Deploy Gerrit on the cluster|-|
@@ -257,6 +263,7 @@ Usage:
   sfconfig microshift [flags]
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -i, --inventory |string  | Specify ansible playbook inventory|-|
@@ -274,6 +281,7 @@ sfconfig prometheus [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -f, --fqdn| string |  The FQDN for prometheus (prometheus.FQDN)|sfop.dev|
@@ -289,6 +297,7 @@ sfconfig runTests [flags]
 ```
 
 Flags:
+
 | Argument | Type | Description | Default |
 |----------|------|-------|----|
 |  -e, --extra-var |string |  Set extra variables, the format of each variable must be `key`=`value`|-|

doc/deployment/config_repository.md

@@ -35,7 +35,7 @@ This setup enables GitOps workflows on the configuration of your Zuul-based CI i
 
 ## Repository structure
 
-For the config-check and config-update to work as expected, a specific file structure is expected in the config repository:
+For the config-check and config-update to work as intended, a specific file structure is expected in the config repository:
 
 ```
 /
@@ -46,10 +46,12 @@ For the config-check and config-update to work as expected, a specific file stru
       |_ nodepool.yaml
 ```
 
-The file `zuul/main.yaml` holds the [tenants configuration](https://zuul-ci.org/docs/zuul/latest/tenants.html) that will be applied the deployment.
+The file `zuul/main.yaml` holds the [tenants configuration](https://zuul-ci.org/docs/zuul/latest/tenants.html) that will be applied on the deployment.
 
 The file `nodepool.yaml` holds [the diskimages, labels and node providers configuration](https://zuul-ci.org/docs/nodepool/latest/configuration.html).
 
+Any other file or folder will be ignored.
+
 ## Setting up the repository
 
 As of the current version of the SF-Operator, Gerrit is the only supported hosting option for the config repository. You can follow the [developer's documentation to deploy a test Gerrit instance](../developer/howtos/index.md#gerrit) if needed.

doc/deployment/crds.md

@@ -5,7 +5,6 @@ This document gives details about the Custom Resource Definitions (CRDs) that th
 ## Table of Contents
 
 1. [CRDs](#crds)
-1. [Common properties](#common-properties)
 
 ## CRDs
 

doc/deployment/delete.md

@@ -19,7 +19,7 @@ This removes the `my-sf` Custom Resource instance.
 ./tools/sfconfig sf delete -i
 ```
 
-However, **Persistent Volumes Claims** linked to the resource are not cleaned after the deletion of the software factory instance.
+However, **Persistent Volume Claims** linked to the resource are not cleaned after the deletion of the software factory instance.
 
 > This is intended, so that it is easy to re-spin an instance with the same configuration and data.
 

doc/deployment/getting_started.md

@@ -22,7 +22,7 @@ We recommend using a dedicated namespace to deploy your Software Factory. Furthe
 > Currently, the namespace must allow `privileged` containers to run. Indeed the `zuul-executor` container requires
 extra privileges because of [bubblewrap](https://github.com/containers/bubblewrap).
 
-For this example we will create **sf** namespace. The last three commands below configure privileged access on this namespace; modify the commands accordingly if using an existing namespace.
+In this example we will create a dedicated namespace called **sf**. Then the next three commands below configure privileged access on this namespace; modify the commands as needed if using a different namespace.
 
 > Note that these commands might need to be run by a user with enough privileges to create and modify namespaces and policies.
 
@@ -33,7 +33,7 @@ kubectl label --overwrite ns sf pod-security.kubernetes.io/enforce-version=v1.24
 oc adm policy add-scc-to-user privileged system:serviceaccount:sf:default
 ```
 
-Create a **SoftwareFactory** Custom Resource as a file named `my-sf.yaml`. Here is a minimal example that uses a default configuration; only the FQDN of the services is mandatory:
+Create a **SoftwareFactory** Custom Resource as a file named `my-sf.yaml`. Here is a minimal example that uses a default configuration; only the base FQDN for the services is mandatory:
 
 ```yaml
 apiVersion: sf.softwarefactory-project.io/v1

doc/deployment/nodepool.md

@@ -29,6 +29,7 @@ The operator also includes backing services with bare bones support:
 
 > Although Zookeeper is deployed as a statefulset, modifying its replica count directly in its manifest
 will have no effect on the service itself - besides eventually creating unused pods.
+
 ## Services configuration
 
 Configuring the Nodepool micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml).

doc/developer/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

doc/developer/index.md

@@ -4,7 +4,8 @@ Welcome to the developer documentation. You can find here what you need to spin
 
 ## Table of Contents
 
-1. [Getting started](./getting_started.md)
+1. [Contribution guidelines](./CONTRIBUTING.md)
+1. [Setting up a development environment](./getting_started.md)
 1. [Running MicroShift](./microshift.md)
 1. [Running tests](./testing.md)
 1. [Release sf-operator](./release.md)

doc/index.md

@@ -1,10 +1,12 @@
 # SF Operator documentation
 
+Welcome to SF-Operator's documentation. To know more about the project's purpose,
+please consult the [README](./README.md).
 ## Table of Contents
 
 1. [Operator documentation](./operator/index.md)
 1. [Deployment documentation](./deployment/index.md)
 1. [Developer documentation](./developer/index.md)
 1. [End User documentation](./user/index.md)
 1. [CLI reference](./cli/index.md)
-1. [Architectural Decision Records](./adr/index.md)
+1. [Architectural Decision Records](./adr/index.md)

doc/operator/index.md

@@ -5,4 +5,4 @@ Welcome to the operator documentation. It covers information about installing an
 ## Table of Contents
 
 1. [Getting started](./getting_started.md)
-1. [Operator removal](./uninstall.md)
+1. [Uninstall the Operator](./uninstall.md)

doc/operator/uninstall.md

@@ -6,7 +6,7 @@ The `sfconfig` command offers the following option:
 ./tools/sfconfig operator delete [OPTIONS]
 
 OPTIONS
-  --subscription, -s - deletes Software Factory Operator's Subscription
+  --subscription, -s - deletes Software Factory Operator Subscription
   --catalogsource, -S - deletes Software Factory Catalog Source
   --clusterserviceversion, -c - deletes Software Factory Cluster Service Version
   --all, -a - executes all options in sequence