From 409e9ad34c94fe372a20ff0705abb06894f8bbf7 Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Fri, 6 Oct 2023 10:13:27 +0200 Subject: [PATCH] Doc: Fix some rendering errors, use cayman theme on gh.io Change-Id: I56a6b44eb83dfed15c03e938d30981428a8daeb5 --- README.md | 16 ++++++++-------- doc/README.md | 1 + doc/_config.yml | 4 ++++ doc/adr/index.md | 16 +++++++++++++++- doc/cli/index.md | 9 +++++++++ doc/deployment/config_repository.md | 6 ++++-- doc/deployment/crds.md | 1 - doc/deployment/delete.md | 2 +- doc/deployment/getting_started.md | 4 ++-- doc/deployment/nodepool.md | 1 + doc/developer/CONTRIBUTING.md | 1 + doc/developer/index.md | 3 ++- doc/index.md | 4 +++- doc/operator/index.md | 2 +- doc/operator/uninstall.md | 2 +- 15 files changed, 53 insertions(+), 19 deletions(-) create mode 120000 doc/README.md create mode 100644 doc/_config.yml create mode 120000 doc/developer/CONTRIBUTING.md diff --git a/README.md b/README.md index b560f950..896aa6cf 100644 --- a/README.md +++ b/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). diff --git a/doc/README.md b/doc/README.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/doc/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/doc/_config.yml b/doc/_config.yml new file mode 100644 index 00000000..c7c0cc16 --- /dev/null +++ b/doc/_config.yml @@ -0,0 +1,4 @@ +theme: cayman +source: doc/ +exclude: + - adr/adr-template.md diff --git a/doc/adr/index.md b/doc/adr/index.md index d130753b..51c26574 100644 --- a/doc/adr/index.md +++ b/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 . General information about architectural decision records is available at . + +## 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) \ No newline at end of file diff --git a/doc/cli/index.md b/doc/cli/index.md index 2fff10ea..b1ad8195 100644 --- a/doc/cli/index.md +++ b/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`|-| diff --git a/doc/deployment/config_repository.md b/doc/deployment/config_repository.md index e1905827..9b9000fd 100644 --- a/doc/deployment/config_repository.md +++ b/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. diff --git a/doc/deployment/crds.md b/doc/deployment/crds.md index c5bbb115..c8f88f10 100644 --- a/doc/deployment/crds.md +++ b/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 diff --git a/doc/deployment/delete.md b/doc/deployment/delete.md index c9b44b94..29b7a240 100644 --- a/doc/deployment/delete.md +++ b/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. diff --git a/doc/deployment/getting_started.md b/doc/deployment/getting_started.md index d8787931..268f9a91 100644 --- a/doc/deployment/getting_started.md +++ b/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 diff --git a/doc/deployment/nodepool.md b/doc/deployment/nodepool.md index 11e95e98..8e32691c 100644 --- a/doc/deployment/nodepool.md +++ b/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). diff --git a/doc/developer/CONTRIBUTING.md b/doc/developer/CONTRIBUTING.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/doc/developer/CONTRIBUTING.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/doc/developer/index.md b/doc/developer/index.md index 1a98f232..6f13c1f6 100644 --- a/doc/developer/index.md +++ b/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) diff --git a/doc/index.md b/doc/index.md index f48adbb5..9f5010bb 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,5 +1,7 @@ # 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) @@ -7,4 +9,4 @@ 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) \ No newline at end of file +1. [Architectural Decision Records](./adr/index.md) diff --git a/doc/operator/index.md b/doc/operator/index.md index 29eab0f4..6bbe57e5 100644 --- a/doc/operator/index.md +++ b/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) \ No newline at end of file +1. [Uninstall the Operator](./uninstall.md) \ No newline at end of file diff --git a/doc/operator/uninstall.md b/doc/operator/uninstall.md index cd401c5c..07bef2c0 100644 --- a/doc/operator/uninstall.md +++ b/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