docs: improve and use docusaurus (#898)

This PR fixes a lot of issues with missing and wrong documentation.
Also, it moves to docusaurus for building the static website.

Missing parts: telemetry / azure stuff, and a nice welcome page.

Author: buehler

.github/workflows/docs-test.yml

@@ -0,0 +1,32 @@
+name: Test Documentation Build
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs-test.yml"
+
+  workflow_dispatch:
+
+jobs:
+  test-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install Dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build Docusaurus
+        working-directory: docs
+        run: npm run build

.github/workflows/gh-pages.yml

@@ -4,6 +4,9 @@ on:
   push:
     branches:
       - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/gh-pages.yml"
 
   workflow_dispatch:
 
@@ -25,18 +28,29 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup .NET
-        uses: actions/setup-dotnet@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          dotnet-version: 9.x
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
 
-      - run: dotnet tool restore
+      - name: Install Dependencies
+        working-directory: docs
+        run: npm ci
 
-      - run: dotnet docfx
+      - name: Build Docusaurus
+        working-directory: docs
+        run: npm run build
 
-      - uses: actions/upload-pages-artifact@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          path: _site
+          path: docs/build
 
-      - uses: actions/deploy-pages@v4
+      - name: Deploy to GitHub Pages
         id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -4,7 +4,7 @@ First of all, thank you for considering contributing to KubeOps.
 This is an open souce project and shall be driven by the community.
 
 This project and everyone participating in it is governed by the
-[KubeOps Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you are
+[KubeOps Code of Conduct](https://github.com/buehler/dotnet-operator-sdk/blob/main/CODE_OF_CONDUCT.md). By participating, you are
 expected to uphold this code. Please report unacceptable behavior by
 [opening a new issue](https://github.com/buehler/dotnet-operator-sdk/issues/new) with the title prefixed with '[CODE OF CONDUCT]'.
 
@@ -15,6 +15,7 @@ to develop on KubeOps.
 
 Feel free to open an issue in the [issues section](https://github.com/buehler/dotnet-operator-sdk/issues).
 There are three issue templates:
+
 - Bug: to report an issue/bug that prevents usage or is an inconvenience of KubeOps
 - Feature request: to report a new feature that would enhance KubeOps
 - Documentation: to report missing / wrong documentation
@@ -25,21 +26,23 @@ Please search through the already created issues to find similarities.
 
 To directly contribute to the solution, create a fork of the repository
 and implement your addition. Please keep in mind that reviewing takes some
-time and is not done instantly.
+time and is not done instantly. The people working on the project are volunteers
+and will do their best to review your PR as soon as possible.
 
 Please adhere to the linting rules and the general code style in the repository.
 Also, add tests for your changes to ensure that the system works well
 when other changes happen.
 
-The PR can have any name, but it would be nice if you adhere to
+The PR name should adhere to
 the repositories standard naming. Please name your PR
-with [Convential Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
+with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
 
 **NOTE for breaking changes**: please state breaking changes
 in the PR description. The review process will be faster when
 breaking changes are well documented.
 
 A few examples:
+
 - "fix: Null exception during watcher process"
 - "feat(core): Add new functionality"
 - "feat(testing): expose kubernetes client for testing"
@@ -50,7 +53,7 @@ The PR will be squashed and merged into the default branch.
 
 ## Local Development
 
-To setup a local development environment, you'll need to perform the follwing steps:
+To set up a local development environment, you'll need to perform the following steps:
 
 - Check out the repository (or your fork)
 - If you want to run the Operator locally, you'll need some Kubernetes instance.
@@ -59,10 +62,11 @@ To setup a local development environment, you'll need to perform the follwing st
   - minikube / any other local Kubernetes
   - Deployed Kubernetes (e.g. GCP Kubernetes instance)
 - You can now code your stuff.
-- `tests/KubeOps.TestOperator` is a developed small operator that can be run
-  locally to test your implementations.
-- Write tests for your changes
+- Use the implementation in the examples folder to test your changes. Those examples
+  may also be extended or new ones added for testing purposes.
+- Write tests for your changes!
 - Build the whole solution and check for linting errors / warnings.
   **NOTE** that any warning will result in an error when building
   with `Release` configuration.
 - Do not change the linting rules without creating a discussion/issue first.
+- Create a PR with an appropriate name and description.