docs: publish user docs using github pages (#80)

lander2k2 · scottd018 · web-flow · commit 341f85633f08 · 2024-08-13T09:27:11.000-04:00
* docs: publish user docs using github pages

Signed-off-by: Rich Lander &lt;lander2k2@protonmail.com&gt;

* docs: correct outdated version and bad list

Also remove snap install since we do not support it.

Signed-off-by: Dustin Scott &lt;dustin.scott18@gmail.com&gt;

* docs: use repo README as docs index

Signed-off-by: Rich Lander &lt;lander2k2@protonmail.com&gt;

* docs: remove repeated content from README

Signed-off-by: Rich Lander &lt;lander2k2@protonmail.com&gt;

---------

Signed-off-by: Rich Lander &lt;lander2k2@protonmail.com&gt;
Signed-off-by: Dustin Scott &lt;dustin.scott18@gmail.com&gt;
Co-authored-by: Dustin Scott &lt;dustin.scott18@gmail.com&gt;
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,18 @@
+---
+name: Docs
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3.5.3
+      - uses: actions/setup-python@v4.6.1
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material mkdocs-material-extensions mike
+      - run: mkdocs gh-deploy --force
+
diff --git a/README.md b/README.md
@@ -12,6 +12,13 @@
 
 **Accelerate the development of Kubernetes operators.**
 
+## Documentation
+
+User documentation can be found at
+[operator-builder.io](https://operator-builder.io).
+
+Developer documentation can be found [here](https://github.com/nukleros/operator-builder/tree/main/docs/dev).
+
 ## What is a Kubernetes Operator?
 
 A Kubernetes operator takes human operational knowledge for managing workloads
@@ -73,8 +80,8 @@ building an app stack management operator with Operator Builder:
   test them in a Kubernetes cluster.  You can also use Helm and the `helm template`
   command to create these resources if a helm chart exists.
 * Determine which fields in the manifests need to be mutable and managed by the
-  operator, then add [markers](docs/markers.md) to the manifests.
-* Create a [workload configuration](docs/workloads.md) to give it some details,
+  operator, then add [markers](https://operator-builder.io/markers) to the manifests.
+* Create a [workload configuration](https://operator-builder.io/workloads) to give it some details,
   such as what you would like to call your custom resource.
 * Run the Operator Builder CLI in a new repository and provide to it the marked
   up manifests and workload config.
@@ -85,16 +92,16 @@ updating or deleting a custom resource instance.
 
 An operator built with Operator Builder has the following features:
 
-* A defined API for a custom resource based on [markers](docs/markers.md) in
+* A defined API for a custom resource based on [markers](https://operator-builder.io/markers) in
   static Kubernetes manifests.
 * A functioning controller that will create, update and delete child resources
   to reconcile the state for the custom resource/s.
-* A [companion CLI](docs/companion-cli.md) that helps end users with common
+* A [companion CLI](https://operator-builder.io/companion-cli) that helps end users with common
   operations.
 
 The custom resource defined in the source code can be cluster-scoped or
 namespace-scoped based on the requirements of the project.  More info
-[here](docs/resource-scope.md).
+[here](https://operator-builder.io/resource-scope).
 
 ## Advanced Functionality
 
@@ -113,34 +120,18 @@ in Go, not to mention the logic for creating, updating and deleting those resour
 Operator Builder adds those resource definitions and other code to get you up
 and running in short order.
 
-## Documentation
-
-### User Docs
+## Roadmap
 
-* [Installation](docs/installation.md)
-* [Getting Started](docs/getting-started.md)
-* [Workloads](docs/workloads.md)
-    * [Standalone Workloads](docs/standalone-workloads.md)
-    * [Workload Collections](docs/workload-collections.md)
-* [Markers](docs/markers.md)
-* [Resource Scope](docs/resource-scope.md)
-* [Companion CLI](docs/companion-cli.md)
-* [API Updates & Upgrades](docs/api-updates-upgrades.md)
-* [License Management](docs/license.md)
+Please view our [roadmap documentation](https://github.com/nukleros/operator-builder/blob/main/ROADMAP.md)
+to learn more about where we are headed and please open a new [issue](
+https://github.com/nukleros/operator-builder/issues) on GitHub if you have an
+idea or want to see something added to the roadmap.
 
-### Developer Docs
+## License
 
-* [Testing](docs/testing.md)
-
-### Roadmap Docs
-
-Please view our [roadmap documentation](ROADMAP.md) to learn more about where we are headed and please open 
-a new [issue](https://github.com/nukleros/operator-builder/issues) on GitHub if you have an idea or want to see 
-something added to the roadmap.
-
-### License
-
-Copyright 2024 [Nukleros](https://github.com/nukleros) and [Third-party Authors](THIRD-PARTY.md) and maintained 
-by a [core group of maintainers](MAINTAINERS.md).
+Copyright 2024 [Nukleros](https://github.com/nukleros) and [Third-party Authors](
+https://github.com/nukleros/operator-builder/tree/main/THIRD-PARTY.md) and maintained
+by a [core group of maintainers](https://github.com/nukleros/operator-builder/tree/main/MAINTAINERS.md).
 
 The software is available under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
+
diff --git a/docs/contact.md b/docs/contact.md
@@ -0,0 +1,18 @@
+# Contact
+
+If you find a bug or issue, please [open an issue on
+Github](https://github.com/nukleros/operator-builder/issues)
+
+If you would like to contribute to Operator Builder:
+
+* Check out the [Contributing
+  Guide](https://github.com/nukleros/operator-builder/blob/main/CONTRIBUTING.md)
+* For simple bug fixes or documentation updates, please [open a
+  PR](https://github.com/nukleros/operator-builder/pulls)
+* For new feature additions or involved changes, please [open an
+  issue](https://github.com/nukleros/operator-builder/issues) before you
+  start work.
+
+For general help or questions, hit us up in the [operator-builder channel on
+Kubernetes Slack](https://kubernetes.slack.com/archives/C02HQCN3NUB)
+
diff --git a/docs/dev/README.md b/docs/dev/README.md
@@ -0,0 +1,7 @@
+# Developer Docs
+
+The documentation here is for developers of Operator Builder.
+
+If you're developing operators using Operator Builder see our [user
+documentation](https://opeator-builder.io/).
+
diff --git a/docs/dev/testing.md b/docs/dev/testing.md
diff --git a/docs/docs/images b/docs/docs/images
@@ -0,0 +1 @@
+../images
diff --git a/docs/images/operator-builder-logo.ico b/docs/images/operator-builder-logo.ico
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,18 +1,18 @@
 # Installation
 
 You have the following options to install the operator-builder CLI:
-* [Download the latest binary with your browser](https://github.com/nukleros/operator-builder/releases/latest)
-* [Download with wget](#wget)
-* [Homebrew](#homebrew)
-* [Docker Image](#docker-image)
-* [Go Install](#go-install)
-* [Snap](#snap)
+
+- [Download the latest binary with your browser](https://github.com/nukleros/operator-builder/releases/latest)
+- [Download with wget](#wget)
+- [Homebrew](#homebrew)
+- [Docker Image](#docker-image)
+- [Go Install](#go-install)
 
 ### wget
 Use wget to download the pre-compiled binaries:
 
 ```bash
-VERSION=v0.7.0
+VERSION=v0.11.0
 OS=Linux
 ARCH=x86_64
 wget https://github.com/nukleros/operator-builder/releases/download/${VERSION}/operator-builder_${VERSION}_${OS}_${ARCH}.tar.gz -O - |\
@@ -61,16 +61,3 @@ operator-builder() {
 ```bash
 go install github.com/nukleros/operator-builder/cmd/operator-builder@latest
 ```
-
-### Snap
-
-**NOTE:** support for Snaps has been removed due to, what we feel, is increasingly unstable developer experience in publishing snaps.  We can readdress 
-this at such a time where stability to the project has returned.  As of now, the latest available snap for operator-builder is v0.5.0.
-
-Available for Linux only.
-
-```bash
-snap install operator-builder
-```
-
->**NOTE**: `operator-builder` installs with [_strict confinement_](https://docs.snapcraft.io/snap-confinement/6233) in snap, this means it doesn't have direct access to root files.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,64 @@
+site_name: Operator Builder
+site_author: Operator Builder developers
+site_description: Documentation for Operator Builder
+repo_url: https://github.com/nukleros/operator-builder
+repo_name: nukleros/operator-builder
+edit_uri: blob/main/docs/
+
+nav:
+  - Home: 'index.md'
+  - Install: 'installation.md'
+  - Getting Started: 'getting-started.md'
+  - Workloads:
+    - Workloads: 'workloads.md'
+    - Standalone Workloads: 'standalone-workloads.md'
+    - Workload Collections: 'workload-collections.md'
+    - Workload Collection Tutorial: 'workload-collection-tutorial/workload-collection-tutorial.md'
+  - Markers: 'markers.md'
+  - Resource Scope: 'resource-scope.md'
+  - Companion CLI: 'companion-cli.md'
+  - License Management: 'license.md'
+  - API Updates & Upgrades: 'api-updates-upgrades.md'
+  - Contact: 'contact.md'
+
+theme:
+  name: material
+  favicon: images/operator-builder-logo.ico
+  logo: images/operator-builder-logo.png
+  features:
+    - content.code.copy
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+    - search
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/threeport/threeport
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - pymdownx.details
+  - pymdownx.highlight:
+      linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - toc:
+      permalink: true
+
+copyright: Copyright &copy; 2022-2024 Operator Builder
+
