[docs] Reorganize hugo doc site (#3382)

This PR reorganizes sdk.operatorframework.io to match the navigation panel for olm.operatorframework.io, so that both the sites appear to be part of one operator-framework family.
operator-framework · Jul 17, 2020 · 1248c1c · 1248c1c
1 parent 3402111
commit 1248c1c
Show file tree

Hide file tree

Showing 118 changed files with 272 additions and 240 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -220,7 +220,7 @@
 - The type name `TestCtx` in `pkg/test` has been deprecated and renamed to `Context`. It now exists only as a type alias to maintain backwards compatibility. Users of the e2e framework should migrate to use the new name, `Context`. The `TestCtx` alias will be removed in a future version. ([2549](https://github.com/operator-framework/operator-sdk/pull/2549))
 
 - The additional of the dependency `inotify-tools` on Ansible based-operator images. ([#2586](https://github.com/operator-framework/operator-sdk/pull/2586))
--  **Breaking Change:** The scorecard feature now only supports YAML config files. So, any config file with other extension is deprecated and should be changed for the YAML format. For further information see [`scorecard config file`](./website/content/en/docs/scorecard/_index.md#config-file) ([#2591](https://github.com/operator-framework/operator-sdk/pull/2591))
+-  **Breaking Change:** The scorecard feature now only supports YAML config files. So, any config file with other extension is deprecated and should be changed for the YAML format. For further information see [`scorecard config file`](./website/content/en/docs/advanced-topics/scorecard/_index.md#config-file) ([#2591](https://github.com/operator-framework/operator-sdk/pull/2591))
 
 ### Removed
 
@@ -465,7 +465,7 @@
 
 ### Changed
 
-- **Breaking Change:** New configuration format for the `operator-sdk scorecard` using config files. See [`doc/test-framework/scorecard`](./website/content/en/docs/scorecard/_index.md) for more info ([#1641](https://github.com/operator-framework/operator-sdk/pull/1641))
+- **Breaking Change:** New configuration format for the `operator-sdk scorecard` using config files. See [`doc/test-framework/scorecard`](./website/content/en/docs/advanced-topics/scorecard/_index.md) for more info ([#1641](https://github.com/operator-framework/operator-sdk/pull/1641))
 - **Breaking change:** CSV config field `role-path` is now `role-paths` and takes a list of strings. Users can now specify multiple `Role` and `ClusterRole` manifests using `role-paths`. ([#1704](https://github.com/operator-framework/operator-sdk/pull/1704))
 - Make `ready` package idempotent. Now, a user can call `Set()` or `Unset()` to set the operator's readiness without knowing the current state. ([#1761](https://github.com/operator-framework/operator-sdk/pull/1761))
 
@@ -534,7 +534,7 @@
 - Unify CLI debug logging under a global `--verbose` flag ([#1361](https://github.com/operator-framework/operator-sdk/pull/1361))
 - [Go module](https://github.com/golang/go/wiki/Modules) support by default for new Go operators and during Ansible and Helm operator migration. The dependency manager used for a new operator can be explicitly specified for new operators through the `--dep-manager` flag, available in [`operator-sdk new`](https://github.com/operator-framework/operator-sdk/blob/v0.8.0/doc/sdk-cli-reference.md#new) and [`operator-sdk migrate`](https://github.com/operator-framework/operator-sdk/blob/v0.8.0/doc/sdk-cli-reference.md#migrate). `dep` is still available through `--dep-manager=dep`. ([#1001](https://github.com/operator-framework/operator-sdk/pull/1001))
 - New optional flag `--custom-api-import` for [`operator-sdk add controller`](https://github.com/operator-framework/operator-sdk/blob/v0.8.0/doc/sdk-cli-reference.md#controller) to specify that the new controller reconciles a built-in or external Kubernetes API, and what import path and identifier it should have. ([#1344](https://github.com/operator-framework/operator-sdk/pull/1344))
-- Operator Scorecard plugin support. Documentation for scorecard plugins can be found in the main scorecard [doc](./website/content/en/docs/scorecard/_index.md). ([#1379](https://github.com/operator-framework/operator-sdk/pull/1379))
+- Operator Scorecard plugin support. Documentation for scorecard plugins can be found in the main scorecard [doc](./website/content/en/docs/advanced-topics/scorecard/_index.md). ([#1379](https://github.com/operator-framework/operator-sdk/pull/1379))
 
 ### Changed
 
@@ -650,7 +650,7 @@
 - Ansible operator proxy added the cache handler which allows the get requests to use the operators cache. [#760](https://github.com/operator-framework/operator-sdk/pull/760)
 - Ansible operator proxy added ability to dynamically watch dependent resource that were created by ansible operator. [#857](https://github.com/operator-framework/operator-sdk/pull/857)
 - Ansible-based operators have leader election turned on by default. When upgrading, add environment variable `POD_NAME` to your operator's Deployment using the Kubernetes downward API. To see an example, run `operator-sdk new --type=ansible ...` and see file `deploy/operator.yaml`.
-- A new command [`operator-sdk scorecard`](https://github.com/operator-framework/operator-sdk/blob/v0.4.0/doc/sdk-cli-reference.md#scorecard) which runs a series of generic tests on operators to ensure that an operator follows best practices. For more information, see the [scorecard documentation](./website/content/en/docs/scorecard/_index.md)
+- A new command [`operator-sdk scorecard`](https://github.com/operator-framework/operator-sdk/blob/v0.4.0/doc/sdk-cli-reference.md#scorecard) which runs a series of generic tests on operators to ensure that an operator follows best practices. For more information, see the [scorecard documentation](./website/content/en/docs/advanced-topics/scorecard/_index.md)
 
 ### Changed
 

diff --git a/hack/generate/cli-doc/gen-cli-doc.go b/hack/generate/cli-doc/gen-cli-doc.go
@@ -39,12 +39,12 @@ func main() {
 		log.Fatalf("Failed to get current directory: %v", err)
 	}
 
-	legacyDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "cli")
+	legacyDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "cli", "ansible-helm")
 	legacyRoot := cli.GetCLIRoot()
 	legacyRoot.DisableAutoGenTag = true
 	recreateDocDir(legacyRoot, legacyDocPath)
 
-	newDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "new-cli")
+	newDocPath := filepath.Join(currentDir, "website", "content", "en", "docs", "cli", "golang")
 	_, newRoot := cli.GetPluginsCLIAndRoot()
 	newRoot.DisableAutoGenTag = true
 	recreateDocDir(newRoot, newDocPath)

diff --git a/release.sh b/release.sh
@@ -38,7 +38,7 @@ if [[ "$VER" != "$CURR_VER" ]]; then
 	exit 1
 fi
 
-INSTALL_GUIDE_FILE="website/content/en/docs/install-operator-sdk.md"
+INSTALL_GUIDE_FILE="website/content/en/docs/installation/install-operator-sdk.md"
 CURR_VER_INSTALL_GUIDE_FILE="$(sed -nr 's/.*RELEASE_VERSION=(.+)/\1/p' "$INSTALL_GUIDE_FILE" | tr -d ' \t\n')"
 if [[ "$VER" != "$CURR_VER_INSTALL_GUIDE_FILE" ]]; then
 	echo "version '$VER' is not set correctly in $INSTALL_GUIDE_FILE"

diff --git a/website/content/en/build/_index.html b/website/content/en/build/_index.html
@@ -24,14 +24,14 @@ <h2 class="of-heading of-heading--md">How can I write an Operator with Operator
               <div class="of-section--largetext__item">
                   <h2 class="of-heading of-heading--xl">Installing the SDK CLI</h2>
                   <div class="of-section--largetext__content">
-                    <p>Follow the steps in the <a href="/docs/install-operator-sdk/">installation guide</a> to learn how to install the Operator SDK CLI tool. If you are using a release version of the SDK, make sure to follow the documentation for that version. You make use any of the following installation processes:</p>
+                    <p>Follow the steps in the <a href="/docs/installation/install-operator-sdk/">installation guide</a> to learn how to install the Operator SDK CLI tool. If you are using a release version of the SDK, make sure to follow the documentation for that version. You make use any of the following installation processes:</p>
                   <ol class="of-list-ordered">
-                    <li>Install the <a href="/docs/install-operator-sdk/#install-from-homebrew-macos">Homebrew</a> (macOS)</li>
-                    <li>Install from <a href="/docs/install-operator-sdk/#install-from-github-release">GitHub</a> release</li>
-                    <li>Compile and install from <a href="/docs/install-operator-sdk/#compile-and-install-from-master">master</a></li>
+                    <li>Install the <a href="/docs/installation/install-operator-sdk/#install-from-homebrew-macos">Homebrew</a> (macOS)</li>
+                    <li>Install from <a href="/docs/installation/install-operator-sdk/#install-from-github-release">GitHub</a> release</li>
+                    <li>Compile and install from <a href="/docs/installation/install-operator-sdk/#compile-and-install-from-master">master</a></li>
                   </ol>
                   </div>
-                  <a href="/docs/install-operator-sdk" class="of-button of-button--tertiary">Learn More
+                  <a href="/docs/installation/install-operator-sdk" class="of-button of-button--tertiary">Learn More
                     <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                         <path d="M19.5,8l-7.3-7.6c-0.4-0.4-1.1-0.4-1.5,0L9.3,1.8c-0.4,0.4-0.4,1.1,0,1.6l5.2,5.5H1.1C0.5,8.9,0,9.3,0,10V12  c0,0.6,0.5,1.1,1.1,1.1h13.5l-5.2,5.5c-0.4,0.4-0.4,1.1,0,1.6l1.4,1.5c0.4,0.4,1.1,0.4,1.5,0l9.4-9.9c0.4-0.4,0.4-1.1,0-1.6L19.5,8z  "/>
                         </svg>
@@ -44,19 +44,19 @@ <h2 class="of-heading of-heading--xl">Installing the SDK CLI</h2>
                 <h2 class="of-heading of-heading--xl">READ THE USER GUIDES</h2>
                 <p class="of-section--largetext__content">Operators can be created with the SDK using Ansible, Helm, or Go. Follow the one of the quickstart guides to dive in.</p>
                 <ul>
-                  <li><a href="/docs/ansible/quickstart/" class="of-button of-button--tertiary">
+                  <li><a href="/docs/building-operators/ansible/quickstart/" class="of-button of-button--tertiary">
                       Ansible Quickstart
                       <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                           <path d="M19.5,8l-7.3-7.6c-0.4-0.4-1.1-0.4-1.5,0L9.3,1.8c-0.4,0.4-0.4,1.1,0,1.6l5.2,5.5H1.1C0.5,8.9,0,9.3,0,10V12  c0,0.6,0.5,1.1,1.1,1.1h13.5l-5.2,5.5c-0.4,0.4-0.4,1.1,0,1.6l1.4,1.5c0.4,0.4,1.1,0.4,1.5,0l9.4-9.9c0.4-0.4,0.4-1.1,0-1.6L19.5,8z  "/>
                       </svg>
                     </a></li>
-                    <li><a href="/docs/helm/quickstart/" class="of-button of-button--tertiary">
+                    <li><a href="/docs/building-operators/helm/quickstart/" class="of-button of-button--tertiary">
                       Helm Quickstart
                       <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                           <path d="M19.5,8l-7.3-7.6c-0.4-0.4-1.1-0.4-1.5,0L9.3,1.8c-0.4,0.4-0.4,1.1,0,1.6l5.2,5.5H1.1C0.5,8.9,0,9.3,0,10V12  c0,0.6,0.5,1.1,1.1,1.1h13.5l-5.2,5.5c-0.4,0.4-0.4,1.1,0,1.6l1.4,1.5c0.4,0.4,1.1,0.4,1.5,0l9.4-9.9c0.4-0.4,0.4-1.1,0-1.6L19.5,8z  "/>
                       </svg>
                       </a></li>
-                      <li><a href="/docs/golang/quickstart/" class="of-button of-button--tertiary">
+                      <li><a href="/docs/building-operators/golang/quickstart/" class="of-button of-button--tertiary">
                       Go Quickstart
                       <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                           <path d="M19.5,8l-7.3-7.6c-0.4-0.4-1.1-0.4-1.5,0L9.3,1.8c-0.4,0.4-0.4,1.1,0,1.6l5.2,5.5H1.1C0.5,8.9,0,9.3,0,10V12  c0,0.6,0.5,1.1,1.1,1.1h13.5l-5.2,5.5c-0.4,0.4-0.4,1.1,0,1.6l1.4,1.5c0.4,0.4,1.1,0.4,1.5,0l9.4-9.9c0.4-0.4,0.4-1.1,0-1.6L19.5,8z  "/>
@@ -80,7 +80,7 @@ <h2 class="of-heading of-heading--xl">PUBLISH YOUR OPERATOR</h2>
                 <h2 class="of-heading of-heading--xl">LEVEL UP YOUR OPERATOR</h2>
                 <p class="of-section--largetext__content">Learn about operator maturity and the requirements to approach full auto
                   pilot.</p>
-                <a href="/docs/operator-capabilities/" class="of-button of-button--tertiary">Learn More
+                <a href="/docs/advanced-topics/operator-capabilities/operator-capabilities" class="of-button of-button--tertiary">Learn More
                   <svg class="of-button__icon" enable-background="new 0 0 22 22" version="1.1" viewBox="0 0 22 22"
                     xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
                     <path

diff --git a/website/content/en/docs/_index.md b/website/content/en/docs/_index.md
@@ -6,92 +6,3 @@ menu:
     weight: 2
 ---
 
-## Overview
-
-This project is a component of the [Operator Framework][of-home], an open source toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. Read more in the [introduction blog post][of-blog].
-
-[Operators][operator_link] make it easy to manage complex stateful applications on top of Kubernetes. However writing an operator today can be difficult because of challenges such as using low level APIs, writing boilerplate, and a lack of modularity which leads to duplication.
-
-The Operator SDK is a framework that uses the [controller-runtime][controller_runtime] library to make writing operators easier by providing:
-
-  - High level APIs and abstractions to write the operational logic more intuitively
-  - Tools for scaffolding and code generation to bootstrap a new project fast
-  - Extensions to cover common operator use cases
-
-## Workflow
-
-The SDK provides workflows to develop operators in Go, Ansible, or Helm.
-
-The following workflow is for a new [Golang operator][golang-guide]:
-
-  1. Create a new operator project using the SDK Command Line Interface(CLI)
-  2. Define new resource APIs by adding Custom Resource Definitions(CRD)
-  3. Define Controllers to watch and reconcile resources
-  4. Write the reconciling logic for your Controller using the SDK and controller-runtime APIs
-  5. Use the SDK CLI to build and generate the operator deployment manifests
-
-The following workflow is for a new [Ansible operator][ansible-guide]:
-
-  1. Create a new operator project using the SDK Command Line Interface(CLI)
-  2. Write the reconciling logic for your object using ansible playbooks and roles
-  3. Use the SDK CLI to build and generate the operator deployment manifests
-  4. Optionally add additional CRD's using the SDK CLI and repeat steps 2 and 3
-
-The following workflow is for a new [Helm operator][helm-guide]:
-
-  1. Create a new operator project using the SDK Command Line Interface(CLI)
-  2. Create a new (or add your existing) Helm chart for use by the operator's reconciling logic
-  3. Use the SDK CLI to build and generate the operator deployment manifests
-  4. Optionally add additional CRD's using the SDK CLI and repeat steps 2 and 3
-
-## Command Line Interface
-
-To learn more about the SDK CLI, see the [SDK CLI Reference][sdk_cli_ref], or run `operator-sdk [command] -h`.
-
-### Operator capability level
-
-Note that each operator type has a different set of capabilities. When choosing what type to use for your project, it is important to understand the features and limitations of each of the project types and the use cases for your operator.
-
-![operator-capability-level](/operator-capability-level.png)
-
-Find more details about the various levels and the feature requirements for them in the [capability level documentation][capability_levels].
-
-## Samples
-
-To explore any operator samples built using the operator-sdk, see the [operator-sdk-samples][samples].
-
-## FAQ
-
-For common Operator SDK related questions, see the [FAQ][faq].
-
-## Contributing
-
-See [CONTRIBUTING][contrib] for details on submitting patches and the contribution workflow.
-
-See the [proposal docs][proposals_docs] and issues for ongoing or planned work.
-
-## Reporting bugs
-
-See [reporting bugs][bug_guide] for details about reporting any issues.
-
-## License
-
-Operator SDK is under Apache 2.0 license. See the [LICENSE][license_file] file for details.
-
-[ansible-guide]:/docs/ansible/quickstart/
-[bug_guide]:/docs/contribution-guidelines/reporting-issues/
-[capability_levels]: /docs/operator-capabilities/
-[contrib]: https://github.com/operator-framework/operator-sdk/blob/master/CONTRIBUTING.MD
-[controller_runtime]: https://github.com/kubernetes-sigs/controller-runtime
-[faq]: /docs/faq/
-[getting_started]: https://github.com/operator-framework/getting-started/blob/master/README.md
-[golang-guide]:/docs/golang/quickstart/
-[helm-guide]:/docs/helm/quickstart/
-[install_guide]: /docs/install-operator-sdk/
-[license_file]:https://github.com/operator-framework/operator-sdk/blob/master/LICENSE
-[of-blog]: https://coreos.com/blog/introducing-operator-framework
-[of-home]: https://github.com/operator-framework
-[operator_link]: https://coreos.com/operators/
-[proposals_docs]: https://github.com/operator-framework/operator-sdk/tree/master/proposals
-[samples]: https://github.com/operator-framework/operator-sdk-samples
-[sdk_cli_ref]: /docs/cli/
diff --git a/website/content/en/docs/advanced-topics/_index.md b/website/content/en/docs/advanced-topics/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Advanced Topics"
+linkTitle: "Advanced Topics"
+weight: 5
+date: 2020-07-09  
+description: Guide to CRD scoping, Operator Scoping and Scorecard testing using Operator SDK
+---
diff --git a/.../content/en/docs/operator-capabilities.md → ...tor-capabilities/operator-capabilities.md b/.../content/en/docs/operator-capabilities.md → ...tor-capabilities/operator-capabilities.md
@@ -1,7 +1,7 @@
 ---
 title: Operator Capability Levels
 linkTitle: Capability Levels
-weight: 50
+weight: 4
 ---
 
 Operators come in different maturity levels in regards to their lifecycle management capabilities for the application or workload they deliver. The capability models aims to provide guidance in terminology to express what features users can expect from an operator.

diff --git a/website/content/en/docs/advanced-topics/scorecard/_index.md b/website/content/en/docs/advanced-topics/scorecard/_index.md
@@ -0,0 +1,6 @@
+---
+title: Scorecard
+linkTitle: Scorecard
+weight: 3
+description: Statically validate your operator bundle using Scorecard. 
+---
diff --git a/...content/en/docs/scorecard/custom-tests.md → ...advanced-topics/scorecard/custom-tests.md b/...content/en/docs/scorecard/custom-tests.md → ...advanced-topics/scorecard/custom-tests.md
@@ -243,6 +243,6 @@ connection to invoke the Kube API.
 [config_yaml]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/testdata/bundle/tests/scorecard/config.yaml
 [scorecard_main_func]: https://github.com/operator-framework/operator-sdk/blob/master/images/scorecard-test/cmd/test/main.go
 [custom_scorecard_repo]: https://github.com/operator-framework/operator-sdk/tree/master/internal/scorecard/examples
-[user_doc]: /docs/scorecard/scorecard/
+[user_doc]: /docs/advanced-topics/scorecard/scorecard/
 [scorecard_binary]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/examples/custom-scorecard-tests/images/custom-scorecard-tests/cmd/test/main.go
 [sample_makefile]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/examples/custom-scorecard-tests/Makefile
diff --git a/.../content/en/docs/scorecard/kuttl-tests.md → .../advanced-topics/scorecard/kuttl-tests.md b/.../content/en/docs/scorecard/kuttl-tests.md → .../advanced-topics/scorecard/kuttl-tests.md
diff --git a/...te/content/en/docs/scorecard/scorecard.md → ...cs/advanced-topics/scorecard/scorecard.md b/...te/content/en/docs/scorecard/scorecard.md → ...cs/advanced-topics/scorecard/scorecard.md
@@ -254,7 +254,7 @@ Writing custom tests in other programming languages is possible
 if the test image follows the above guidelines.
 
 
-[cli-scorecard]: /docs/cli/operator-sdk_scorecard/
+[cli-scorecard]: /docs/cli/golang/operator-sdk_scorecard/
 [sample-config]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/testdata/bundle/tests/scorecard/config.yaml
 [custom-image]: https://github.com/operator-framework/operator-sdk/blob/master/internal/scorecard/examples/custom-scorecard-tests
 [scorecard-struct]: https://github.com/operator-framework/operator-sdk/blob/master/pkg/apis/scorecard/v1alpha3/types.go

diff --git a/website/content/en/docs/building-operators/_index.md b/website/content/en/docs/building-operators/_index.md
@@ -0,0 +1,9 @@
+
+---
+title: "Building Operators"
+linkTitle: "Building Operators"
+weight: 3
+date: 2020-07-09
+description: >
+  Building operators using Operator SDK.
+---
diff --git a/website/content/en/docs/ansible/OWNERS → ...en/docs/building-operators/ansible/OWNERS b/website/content/en/docs/ansible/OWNERS → ...en/docs/building-operators/ansible/OWNERS
diff --git a/website/content/en/docs/ansible/_index.md → ...docs/building-operators/ansible/_index.md b/website/content/en/docs/ansible/_index.md → ...docs/building-operators/ansible/_index.md
@@ -1,6 +1,7 @@
 ---
-title: Ansible Based Operators
-weight: 20
+title: Ansible
+weight: 1
+description: Guide to building a Ansible Based Operator using Operator SDK
 ---
 
 Ansible based operators run playbooks and roles to react to changes in tracked Kubernetes resources (usually CRs).
diff --git a/...ntent/en/docs/ansible/development-tips.md → ...ing-operators/ansible/development-tips.md b/...ntent/en/docs/ansible/development-tips.md → ...ing-operators/ansible/development-tips.md
@@ -509,4 +509,4 @@ operator. The `meta` fields can be accesses via dot notation in Ansible as so:
 [manage_status_proposal]:../../proposals/ansible-operator-status.md
 [time_pkg]:https://golang.org/pkg/time/
 [time_parse_duration]:https://golang.org/pkg/time/#ParseDuration
-[watches]:/docs/ansible/reference/watches
+[watches]:/docs/building-operators/ansible/reference/watches