First stab at doc hierarchy

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

CONTRIBUTING.md

@@ -7,15 +7,16 @@ Operator Controller is an Apache 2.0 licensed project and accepts contributions
 By contributing to this project you agree to the Developer Certificate of
 Origin (DCO). This document was created by the Linux Kernel community and is a
 simple statement that you, as a contributor, have the legal right to make the
-contribution. See the [DCO](DCO) file for details.
+contribution. See the [DCO](https://github.com/operator-framework/operator-controller/blob/main/DCO) file for details.
 
 ## Overview
 
 Thank you for your interest in contributing to the Operator-Controller.
 
-As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](github.com/operator-framework/operator-lifecycle-manager).
+As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](https://github.com/operator-framework/operator-lifecycle-manager).
 
 The user experience captured in the OLM V1 PRD introduces many requirements that are best satisfied by a microservices architecture. The OLM V1 experience currently relies on two projects:
+
 - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
 - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
 
@@ -45,14 +46,15 @@ Please keep this workflow in mind as you read through the document.
 ## How are Milestones Designed?
 
 It's unreasonable to attempt to consider all of the design requirements laid out in the [OLM V1 PRD](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit) from the onset of the project. Instead, the community attempts to design Milestones with the following principles:
+
 - Milestones are tightly scoped units of work, ideally lasting one to three weeks.
 - Milestones are derived from the OLM V1 PRD.
 - Milestones are "demo driven", meaning that a set of acceptance criteria is defined upfront and the milestone is done as soon as some member of the community can run the demo.
 - Edge cases found during development are captured in issues and assigned to the GA Milestone, which contains a list of issues that block the release of operator-controller v1.0.0 .
 
 This "demo driven" development model will allow us to collect user experience and regularly course correct based on user feedback. Subsequent milestone may revert features or change the user experience based on community feedback.
 
-The project maintainer will create a [GitHub Discussion](github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
+The project maintainer will create a [GitHub Discussion](https://github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
 
 ## Where are Operator Controller Milestones?
 
@@ -67,6 +69,7 @@ As discussed earlier, the operator-controller adheres to a microservice architec
 ## Submitting Issues
 
 Unsure where to submit an issue? 
+
 - [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
 - [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
 
@@ -87,7 +90,7 @@ approach of changes.
 When contributing changes that require a new dependency, check whether it's feasible to directly vendor that
 code [without introducing a new dependency](https://go-proverbs.github.io/).
 
-Currently, PRs require at least one approval from a operator-controller maintainer in order to get merged.
+Currently, PRs require at least one approval from an operator-controller maintainer in order to get merged.
 
 ### Code style
 

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,10 @@
+/* Hide banner title */
+.md-header__title {
+    visibility: hidden;
+}
+
+/* Make top-level navigation items bold */
+.md-nav__item--active > .md-nav__link, /* Active top-level items */
+.md-nav__item--nested > .md-nav__link { /* Nested top-level items */
+    font-weight: bold;
+}