Merge pull request #321 from fluxcd/docs/revamp

docs: complete overhaul and switch to `mkdocs`

.circleci/config.yml

@@ -66,7 +66,6 @@ jobs:
       - run: make check-generated
       - run: make test TEST_FLAGS="-race -timeout 5m"
       - run: make all
-      - run: make test-docs
       - e2e_tests:
           helm_version: v2
       - e2e_tests:

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Create a report to help us improve the Flux Helm operator
+about: Create a report to help us improve the Helm Operator
 title: ''
 labels: blocked needs validation, bug
 assignees: ''
@@ -14,7 +14,7 @@ A clear and concise description of what the bug is.
 **To Reproduce**
 
 Steps to reproduce the behaviour:
-1. Provide the Helm operator install instructions
+1. Provide the Helm Operator install instructions
 2. Provide a HelmRelease example
 3. Post the HelmRelease status, you can get this by running `kubectl describe helmrelease <name>`
 
@@ -28,7 +28,7 @@ If applicable, please provide logs. In a standard stand-alone installation, you'
 
 **Additional context**
 
-- Helm operator version: 
+- Helm Operator version: 
 - Kubernetes version:
 - Git provider:
 - Helm repository provider:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
 name: Feature request
-about: Suggest a new feature for the Flux Helm operator
+about: Suggest a new feature for the Helm Operator
 title: ''
 labels: blocked needs validation, enhancement
 assignees: ''
@@ -11,7 +11,7 @@ assignees: ''
 A clear and concise description of the feature.
 
 **What would the new user story look like?**
-How would the new interaction with the Flux Helm operator look like? E.g.
+How would the new interaction with the Helm Operator look like? E.g.
 0. What are the prerequisites for this?
 1. User starts up the operator using the --add-frobnication flag
 2. A new `HelmRelease` is applied

.github/ISSUE_TEMPLATE/helm_v3_bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Helm v3 bug report
-about: Create a bug report for Flux Helm operator with Helm v3
+about: Create a bug report for Helm Operator with Helm v3
 title: ''
 labels: blocked needs validation, bug, helm-v3
 assignees: ''
@@ -26,7 +26,7 @@ If applicable, please provide logs. In a standard stand-alone installation, you'
 
 **Additional context**
 Add any other context about the problem here, e.g 
-- Helm operator version: 
+- Helm Operator version: 
 - Targeted Helm version:
 - Kubernetes version:
 - Git provider:

.github/workflows/check-links.yaml

@@ -0,0 +1,27 @@
+on: [push, pull_request]
+name: Check links
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      - name: Build docs for link check
+        run: mkdocs build
+      - name: Link Checker
+        id: lc
+        uses: peter-evans/link-checker@v1
+        with:
+          args: -r -d site/ -v site/index.html
+      - name: Fail if there were link errors
+        run: exit ${{ steps.lc.outputs.exit_code }}

.gitignore

@@ -52,4 +52,4 @@ test/bin/
 test/e2e/bats
 
 # Docs
-docs/_build
+site/

.readthedocs.yaml

@@ -4,13 +4,9 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-
 # Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
+mkdocs:
+  configuration: mkdocs.yml
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all

CHANGELOG.md

@@ -3,7 +3,7 @@
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 > **Notice:**  due to the multiple added fields, you need to
 > re-apply the `HelmRelease` CRD.
@@ -86,7 +86,7 @@ release, feedback, and reporting issues.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 > **Notice:**  due to the multiple added fields, you need to
 > re-apply the `HelmRelease` CRD.
@@ -179,7 +179,7 @@ this release, feedback, and reporting issues.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 ### Bug fixes
 
@@ -221,7 +221,7 @@ to this release, feedback, and reporting issues.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 This release fixes some (but not all) of the more critical bugs
 reported since Helm v3 was introduced in the last release.
@@ -265,7 +265,7 @@ issues.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 > **Notice:**  due to the added `helmVersion` field, you need
 > to re-apply the `HelmRelease` CRD.
@@ -347,7 +347,7 @@ v3 support, notably @gsf, @dminca, @rowecharles, @eschereisin,
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 ### Improvements
 
@@ -379,7 +379,7 @@ and @stefanprodan for contributions to this release.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 This is the third release candidate.
 
@@ -412,7 +412,7 @@ for contributions to this release.
 > **Notice:** upgrading to this version from `<=0.10.x` by just
 > updating your Helm Operator image tag is not possible as the
 > CRD domain and version have changed. An upgrade guide can be
-> found [here](./docs/guides/upgrading-to-ga.md).
+> found [here](./docs/how-to/upgrading-to-ga.md).
 
 This is the second release candidate.
 
@@ -467,7 +467,7 @@ for contributions to this release.
 
 > **Notice:** upgrading to this version by just updating your Helm
 > Operator image tag is not possible as the CRD domain and version
-> have changed. An upgrade guide can be found [here](./docs/guides/upgrading-to-ga.md).
+> have changed. An upgrade guide can be found [here](./docs/how-to/upgrading-to-ga.md).
 
 This is the first `1.0.0` release candidate, there is no rule about
 the amount of published release candidates before it is officially

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # How to Contribute
 
-The Flux Helm operator is [Apache 2.0 licensed](LICENSE) and accepts contributions
+The Helm Operator is [Apache 2.0 licensed](LICENSE) and accepts contributions
 via GitHub pull requests. This document outlines some of the conventions on development
 workflow, commit message formatting, contact points and other resources to make
 it easier to get your contribution accepted.

Makefile

@@ -32,8 +32,6 @@ IMAGE_TAG:=$(shell ./docker/image-tag)
 VCS_REF:=$(shell git rev-parse HEAD)
 BUILD_DATE:=$(shell date -u +'%Y-%m-%dT%H:%M:%SZ')
 
-DOCS_PORT:=8000
-
 all: $(GOBIN)/bin/helm-operator build/.helm-operator.done
 
 clean:
@@ -150,13 +148,3 @@ generate-deploy: generate-crds pkg/install/generated_templates.gogen.go
 check-generated: generate-deploy pkg/install/generated_templates.gogen.go
 	git diff --exit-code -- pkg/install/generated_templates.gogen.go
 	./hack/update/verify.sh
-
-build-docs:
-	@cd docs && docker build -t flux-docs .
-
-test-docs: build-docs
-	@docker run -it flux-docs /usr/bin/linkchecker _build/html/index.html
-
-serve-docs: build-docs
-	@echo Stating docs website on http://localhost:${DOCS_PORT}/_build/html/index.html
-	@docker run -i -p ${DOCS_PORT}:8000 -e USER_ID=$$UID flux-docs

README.md

@@ -4,18 +4,17 @@
 [![GoDoc](https://godoc.org/github.com/fluxcd/helm-operator?status.svg)](https://godoc.org/github.com/fluxcd/helm-operator)
 [![Documentation](https://img.shields.io/badge/latest-documentation-informational)](https://docs.fluxcd.io/projects/helm-operator/en/latest/)
 
-The Helm operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
+The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
 allowing one to declaratively manage Helm chart releases. Combined with
-[Flux](https://github.com/fluxcd/flux) this can be utilized to automate
-releases in a GitOps manner, but the usage of Flux is not a strict
-requirement.
+[Flux](https://github.com/fluxcd/flux) it can to automate releases in a
+GitOps manner, but the use of Flux is not a strict requirement.
 
 The desired state of a Helm release is described through a Kubernetes
 Custom Resource named `HelmRelease`. Based on the creation, mutation or
 removal of a `HelmRelease` resource in the cluster, Helm actions are
 performed by the operator.
 
-![GitOps Helm Operator](docs/_files/fluxcd-helm-operator-diagram.png)
+![Helm Operator](docs/_files/fluxcd-helm-operator-diagram.png)
 
 ## Helm Operator features
 
@@ -31,7 +30,7 @@ performed by the operator.
     or a (local) URL
 * Automated purging on release install failures
 * Automated (optional) rollback on upgrade failures
-* Automated image upgrades [using Flux](https://docs.fluxcd.io/en/latest/references/helm-operator-integration.html)
+* Automated image upgrades [using Flux](https://docs.fluxcd.io/en/stable/references/helm-operator-integration.html)
 * Automated (configurable) chart dependency updates for Helm charts
   from Git sources on install or upgrade
 * Detection and recovery from Helm storage mutations
@@ -43,25 +42,26 @@ performed by the operator.
 
 ## Get started with the Helm Operator
 
-Get started [installing the Helm operator](/chart/helm-operator/README.md)
-or just [browse through the documentation](https://docs.fluxcd.io/projects/helm-operator/en/latest/).
+Get started [installing the Helm Operator](/chart/helm-operator/README.md)
+or just [browse through the documentation](https://docs.fluxcd.io/projects/helm-operator/en/stable/).
 
 ### Integrations
 
-As Flux Helm Operator is Open Source, integrations are very straight-forward. Here are
-a few popular ones you might want to check out:
+As the Helm Operator is Open Source, integrations are very straight-forward. Here
+are a few popular ones you might want to check out:
 
-- [Progressive Delivery workshop (Helm v3 alpha)](https://helm.workshop.flagger.dev/)
+- [Progressive Delivery workshop](https://helm.workshop.flagger.dev/)
 - [Managing Helm releases the GitOps way](https://github.com/fluxcd/helm-operator-get-started)
 - [GitOps for Istio Canary deployments](https://github.com/stefanprodan/gitops-istio)
 
 ## Community & Developer information
 
-We welcome all kinds of contributions to Helm Operator, be it code, issues you found,
-documentation, external tools, help and support or anything else really.
+We welcome all kinds of contributions to the Helm Operator, be it code, issues
+you found, documentation, external tools, help and support or anything else
+really.
 
-The FluxCD projects adheres to the [CNCF Code of
-Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
+The Helm Operator and other projects in the FluxCD umbrella adhere to the [CNCF
+Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
 
 Instances of abusive, harassing, or otherwise unacceptable behavior
 may be reported by contacting a _Flux_ project maintainer, or the CNCF
@@ -71,17 +71,17 @@ To familiarise yourself with the project and how things work, you might
 be interested in the following:
 
 - [Our contributions guidelines](CONTRIBUTING.md)
-- [Build documentation](https://docs.fluxcd.io/en/latest/contributing/building.html)
+- [Build documentation](https://docs.fluxcd.io/en/stable/contributing/building.html)
 - [Release documentation](/internal_docs/releasing.md)
 
 ## <a name="help"></a>Getting Help
 
-If you have any questions about Helm Operator and continuous delivery:
+If you have any questions about the Helm Operator and continuous delivery:
 
 - Read [the Helm Operator docs](https://docs.fluxcd.io/projects/helm-operator/).
-- Invite yourself to the <a href="https://slack.cncf.io" target="_blank">CNCF community</a>
-  slack and ask a question on the [#flux](https://cloud-native.slack.com/messages/flux/)
-  channel.
+- Invite yourself to the <a href="https://slack.cncf.io" target="_blank">CNCF
+  community</a> slack and ask a question on the
+  [#flux](https://cloud-native.slack.com/messages/flux/) channel.
 - To be part of the conversation about Helm Operator's development, join the
   [flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev).
 - [File an issue.](https://github.com/fluxcd/helm-operator/issues/new)