First stab at doc hierarchy

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

Makefile

@@ -312,17 +312,18 @@ quickstart: $(KUSTOMIZE) manifests #EXHELP Generate the installation release man
 OPERATOR_CONTROLLER_API_REFERENCE_FILENAME := operator-controller-api-reference.md
 CATALOGD_API_REFERENCE_FILENAME := catalogd-api-reference.md
 CATALOGD_TMP_DIR := $(ROOT_DIR)/.catalogd-tmp/
+API_REFERENCE_DIR := $(ROOT_DIR)/docs/api-reference
 crd-ref-docs: $(CRD_REF_DOCS) #EXHELP Generate the API Reference Documents.
-	rm -f $(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
+	rm -f $(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME)
 	$(CRD_REF_DOCS) --source-path=$(ROOT_DIR)/api \
-	--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
-	--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
+	--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
+	--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(OPERATOR_CONTROLLER_API_REFERENCE_FILENAME);
 	rm -rf $(CATALOGD_TMP_DIR)
 	git clone --depth 1 --branch $(CATALOGD_VERSION) https://github.com/operator-framework/catalogd $(CATALOGD_TMP_DIR)
-	rm -f $(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
+	rm -f $(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
 	$(CRD_REF_DOCS) --source-path=$(CATALOGD_TMP_DIR)/api \
-	--config=$(ROOT_DIR)/docs/refs/api/crd-ref-docs-gen-config.yaml \
-	--renderer=markdown --output-path=$(ROOT_DIR)/docs/refs/api/$(CATALOGD_API_REFERENCE_FILENAME)
+	--config=$(API_REFERENCE_DIR)/crd-ref-docs-gen-config.yaml \
+	--renderer=markdown --output-path=$(API_REFERENCE_DIR)/$(CATALOGD_API_REFERENCE_FILENAME)
 	rm -rf $(CATALOGD_TMP_DIR)/
 
 VENVDIR := $(abspath docs/.venv)

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/developer.md → docs/contribute/developer.md

@@ -177,4 +177,4 @@ done
 
 ## Contributing
 
-Refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.
+Refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more information.

docs/css/extra.css

@@ -0,0 +1,7 @@
+/*.md-nav__title {*/
+/*    visibility: hidden;*/
+/*}*/
+
+.md-header__title {
+    visibility: hidden;
+}

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

@@ -1,5 +1,3 @@
-# Getting Started with OLM v1
-
 ### Installation
 
 The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
@@ -14,7 +12,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:
 
@@ -26,11 +24,11 @@ This quickstart procedure will guide you through the following processes:
 
 OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
 These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
-can be found [here](./docs/Tasks/adding-a-catalog).
+can be found [here](../tutorials/add-catalog).
 
 The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
 extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
-will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md).
+will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](../howto/catalog-queries.md).
 
 To create the catalog, run the following command:
 
@@ -62,7 +60,7 @@ kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeou
 For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator.
 The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions
 needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
-More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).
+More information on installing extensions can be found [here](../tutorials/install-extension.md).
 
 ```bash
 # Apply the sample ClusterExtension. Manifest already includes
@@ -74,29 +72,29 @@ kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-c
 
 To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
 there must be CRD compatibility between the versions being upgraded, and the target version must be
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
-compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md),
-and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
+and on the extension upgrade process [here](../tutorials/upgrade-extension).
 
 ```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"}}}}'
 
 ```
 
-For information on the downgrade process, see [here](docs/drafts/downgrading-an-extension.md).
+For information on the downgrade process, see [here](../tutorials/downgrade-extension.md).
 
 ### Uninstall the Cluster Extension
 
 To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
-remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
+remove all resources created by the extension. More information on uninstalling extensions can be found [here](../tutorials/uninstall-extension.md).
 
 ```bash
 # Delete cluster extension and residing namespace
 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.