First stab at doc hierarchy

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>

README.md

@@ -16,11 +16,11 @@ OLM v1 consists of two different components:
 * operator-controller (this repository)
 * [catalogd](https://github.com/operator-framework/catalogd)
 
-For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/general/olmv1_design_decisions.md).
+For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/project/olmv1_design_decisions.md).
 
 ## Getting Started
 
-To get started with OLM v1, please see our [Getting Started](docs/general/olmv1_getting_started.md) documentation.
+To get started with OLM v1, please see our [Getting Started](docs/getting-started/olmv1_getting_started.md) documentation.
 
 ## License
 

docs/refs/controlling-catalog-selection.md → docs/concepts/controlling-catalog-selection.md

@@ -27,7 +27,7 @@ spec:
   catalog:
     selector:
       matchLabels:
-        olm.operatorframework.io/metadata.name: my-catalog
+        olm.operatorframework.io/metadata.name: my-content-management
 ```
 
 In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
@@ -93,7 +93,7 @@ spec:
         - key: olm.operatorframework.io/metadata.name
           operator: NotIn
           values:
-            - unwanted-catalog
+            - unwanted-content-management
 ```
 
 This excludes the catalog named `unwanted-catalog` from consideration.
@@ -134,7 +134,7 @@ spec:
   source:
     type: image
     image:
-      ref: quay.io/example/high-priority-catalog:latest
+      ref: quay.io/example/high-priority-content-management:latest
 ```
 
 Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution.
@@ -171,7 +171,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-a:latest
+         ref: quay.io/example/content-management-a:latest
    ```
 
    ```yaml
@@ -186,7 +186,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-b:latest
+         ref: quay.io/example/content-management-b:latest
    ```
    NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
 
@@ -209,8 +209,8 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
 3. **Apply the Resources**
 
    ```shell
-   kubectl apply -f catalog-a.yaml
-   kubectl apply -f catalog-b.yaml
+   kubectl apply -f content-management-a.yaml
+   kubectl apply -f content-management-b.yaml
    kubectl apply -f install-my-operator.yaml
    ```
 

docs/refs/single-owner-objects.md → docs/concepts/single-owner-objects.md

@@ -1,4 +1,3 @@
-
 # OLM Ownership Enforcement for `ClusterExtensions`
 
 In OLM, **a Kubernetes resource can only be owned by a single `ClusterExtension` at a time**. This ensures that resources within a Kubernetes cluster are managed consistently and prevents conflicts between multiple `ClusterExtensions` attempting to control the same resource.
@@ -15,6 +14,7 @@ Operator bundles provide `CustomResourceDefinitions` (CRDs), which are part of a
 
 
 ### 2. `ClusterExtensions` Cannot Share Objects
+
 OLM's single-owner policy means that **`ClusterExtensions` cannot share ownership of any resources**. If one `ClusterExtension` manages a specific resource (e.g., a `Deployment`, `CustomResourceDefinition`, or `Service`), another `ClusterExtension` cannot claim ownership of the same resource. Any attempt to do so will be blocked by the system.
 
 ## Error Messages

docs/tasks/upgrade/upgrade-support.md → docs/concepts/upgrade-support.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - toc
+---
+
 # Upgrade support
 
 This document explains how OLM v1 handles upgrades.

docs/refs/version-ranges.md → docs/concepts/version-ranges.md

@@ -4,7 +4,7 @@ This document explains how to specify a version range to install or update an ex
 
 You define a version range in a ClusterExtension's custom resource (CR) file.
 
-## Specifying a version range in the CR
+### Specifying a version range in the CR
 
 If you specify a version range in the ClusterExtension's CR, OLM 1.0 installs or updates the latest version of the extension that can be resolved within the version range.
 The resolved version is the latest version of the extension that satisfies the dependencies and constraints of the extension and the environment.

docs/contribute/contributing.md

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

docs/general/olmv1_getting_started.md → docs/getting-started/olmv1_getting_started.md

@@ -1,4 +1,8 @@
-# Getting Started with OLM v1
+---
+hide:
+  - navigation
+
+---
 
 ### Installation
 
@@ -14,7 +18,7 @@ The latest version of Operator Controller can be installed with the following co
 curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
 ```
 
-## Getting Started with OLM v1
+### Getting Started with OLM v1
 
 This quickstart procedure will guide you through the following processes:
 
@@ -80,7 +84,7 @@ and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-ext
 
 ```bash
 # Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}'
 
 ```
 
@@ -96,7 +100,7 @@ remove all resources created by the extension. More information on uninstalling
 kubectl delete clusterextension/argocd
 ```
 
-#### Cleanup
+### Cleanup
 
 Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
 extension is uninstalled, these resources can be cleaned up.

docs/drafts/derive-serviceaccount.md → docs/howto/derive-service-account.md

@@ -1,6 +1,6 @@
 # Derive minimal ServiceAccount required for ClusterExtension Installation and Management
 
-OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../refs/supported-extensions.md), 
+OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../project/supported-extensions.md), 
 OLM must be provided a ServiceAccount configured with the appropriate permissions. For more information, see the [provided ServiceAccount](./provided-serviceaccount.md) documentation.
 
 This document serves as a guide for how to derive the RBAC necessary to install a bundle.
@@ -12,6 +12,7 @@ This bundle image contains all the manifests that make up the extension (e.g. `C
 as well as a [`ClusterServiceVersion`](https://olm.operatorframework.io/docs/concepts/crds/clusterserviceversion/) (CSV) that describes the extension and its service account's permission requirements.
 
 The service account must have permissions to:
+
  - create and manage the extension's `CustomResourceDefinition`s
  - create and manage the resources packaged in the bundle
  - grant the extension controller's service account the permissions it requires for its operation

docs/tasks/upgrade/how-to-channel-based-upgrades.md → docs/howto/how-to-channel-based-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Channel-Based Automatic Upgrades
+# Channel-Based Automatic Upgrades
 
 A "channel" is a package author defined stream of updates for an extension. A set of channels can be set in the Catalog source to restrict automatic updates to the set of versions defined in those channels.
 

docs/tasks/upgrade/how-to-pin-version.md → docs/howto/how-to-pin-version.md

@@ -1,4 +1,4 @@
-## How-to: Version Pin and Disable Automatic Updates
+# Pin Version and Disable Automatic Updates
 
 To disable automatic updates, and pin the version of an extension, set `version` in the Catalog source to a specific version (e.g. 1.2.3).
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)

docs/tasks/upgrade/how-to-version-range-upgrades.md → docs/howto/how-to-version-range-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Version Range Automatic Updates
+# Version Range Automatic Updates
 
 Set the version for the desired package in the Catalog source to a comparison string, like  `">=3.0, <3.6"`, to restrict the automatic updates to the version range. Any new version of the extension released in the catalog within this range will be automatically applied.
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version-rages](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version-rages](../concepts/version-ranges.md)

docs/tasks/upgrade/how-to-z-stream-upgrades.md → docs/howto/how-to-z-stream-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Z-Stream Automatic Updates
+# Z-Stream Automatic Updates
 
 To restrict automatic updates to only z-stream patches and avoid breaking changes, use the `"~"` version range operator when setting the version for the desired package in Catalog source.
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)

docs/general/olmv1_overview.md → docs/index.md

@@ -1,15 +1,18 @@
-# Overview
+---
+hide:
+  - toc
+---
 
-## What is Operator Lifecycle Manager (OLM)?
+# Overview
 
-Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the 
-lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing, 
+Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the
+lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing,
 running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster administrators and PaaS administrators.
 
-Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.). 
+Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.).
 Operators are a method of packaging, deploying, and managing a Kubernetes application. An Operator is composed of one or more controllers paired with one or both of the following objects:
 
-* One or more API extensions 
+* One or more API extensions
 * One or more [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRDs).
 
 OLM helped define lifecycles for these extensions: from packaging and distribution to installation, configuration, upgrade, and removal.
@@ -27,7 +30,7 @@ is a popular destination for discovering Operators, and boasts over 300 packages
 ## Why are we building OLM v1?
 
 OLM v0 has been in production for over 5 years, and the community to leverage this experience and question the initial
-goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience. 
+goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience.
 Compared to its predecessor, amongst other things, OLM v1 aims to provide:
 
 * A simpler API surface and mental model
@@ -37,19 +40,19 @@ Compared to its predecessor, amongst other things, OLM v1 aims to provide:
 * Helm Chart support
 * GitOps support
 
-To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](olmv1_design_decisions.md) 
-and our feature [Roadmap](olmv1_roadmap.md).
+To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](project/olmv1_design_decisions.md)
+and our feature [Roadmap](project/olmv1_roadmap.md).
 
 ## The OLM community
 
-In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors. 
-The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/), 
+In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors.
+The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/),
 which provides a great entry point to quickly find something interesting to work on and contribute.
 
 You can reach out to the OLM community for feedbacks/discussions/contributions in the following channels:
 
-  * Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev)
-  * [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework)
-  * Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
+* Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev)
+* [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework)
+* Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
 
-For further information on contributing, please consult the [Contribution Guide](../../CONTRIBUTING.md)
+For further information on contributing, please consult the [Contribution Guide](../CONTRIBUTING.md)

docs/general/architecture.md → docs/project/olmv1_architecture.md

@@ -1,5 +1,9 @@
+---
+hide:
+  - toc
+---
 
-## OLM V1 Architecture
+# OLM V1 Architecture
 
 This document describes the OLM v1 architecture. OLM v1 consists of two main components:
 

docs/general/olmv1_design_decisions.md → docs/project/olmv1_design_decisions.md

@@ -1,4 +1,4 @@
-# The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts
+# Multi-Tenancy Challenges, Lessons Learned, and Design Shifts
 
 This provides historical context on the design explorations and challenges that led to substantial design shifts between 
 OLM v1 and its predecessor. It explains the technical reasons why OLM v1 cannot support major v0 features, such as, 

docs/general/olmv1_roadmap.md → docs/project/olmv1_roadmap.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - toc
+---
+
 ---
 title: Product Requriement Doc
 layout: default

docs/refs/supported-extensions.md → docs/project/supported-extensions.md

@@ -1,8 +1,15 @@
+---
+hide:
+  - toc
+---
+
+## OLM v0 Extension Support
+
 Currently, OLM v1 supports installing cluster extensions that meet the following criteria:
 
 * The extension must support installation via the `AllNamespaces` install mode.
 * The extension must not use webhooks.
-* The extension must not declare dependencies using the any of  following file-based catalog properties:
+* The extension must not declare dependencies using any of the following file-based catalog properties:
 
     * `olm.gvk.required`
     * `olm.package.required`