Merge pull request #2919 from fluxcd/move-to-mkdocs

move to mkdocs

.circleci/config.yml

@@ -102,7 +102,6 @@ jobs:
       - run: make check-generated
       - run: make all
       - run: E2E_KIND_CLUSTER_NUM=4 make e2e
-      - run: make test-docs
       - save_cache:
           key: cache-{{ checksum "Makefile" }}
           paths:

.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

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

.readthedocs.yml

@@ -5,13 +5,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

Makefile

@@ -35,8 +35,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
-
 GENERATED_TEMPLATES_FILE=pkg/install/generated_templates.gogen.go
 
 all: $(GOBIN)/fluxctl $(GOBIN)/fluxd build/.flux.done
@@ -187,12 +185,8 @@ build-fluxctl: release-bins
 		--build-arg BUILD_DATE="$(BUILD_DATE)" \
 		-f ./build/docker/fluxctl/Dockerfile ./build/docker/fluxctl
 
-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
+docs-deps:
+	pip3 install -r docs/requirements.txt
 
-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
+serve-docs: docs-deps
+	mkdocs serve

README.md

@@ -81,8 +81,8 @@ could easily integrate.
 
 With the following tutorials:
 
-- [Get started with Flux](https://docs.fluxcd.io/en/latest/tutorials/get-started.html)
-- [Get started with Flux using Helm](https://docs.fluxcd.io/en/latest/tutorials/get-started-helm.html)
+- [Get started with Flux](https://docs.fluxcd.io/en/latest/tutorials/get-started)
+- [Get started with Flux using Helm](https://docs.fluxcd.io/en/latest/tutorials/get-started-helm)
 
 or just [browse through the documentation](https://docs.fluxcd.io).
 
@@ -116,7 +116,7 @@ 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/latest/contributing/building)
 - [Release documentation](/internal_docs/releasing.md)
 
 ## <a name="help"></a>Getting Help

chart/flux/CHANGELOG.md

@@ -31,7 +31,7 @@ Please see the [install instruction](https://github.com/fluxcd/helm-operator/tre
 for Helm Operator v1.0.0. To keep using the same SSH key as Flux see the docs
 [here](https://github.com/fluxcd/helm-operator/tree/master/chart/helm-operator#use-fluxs-git-deploy-key).
 The upgrade procedure for `HelmReleases` from `v1beta1` to `v1` can be found
-[here](https://docs.fluxcd.io/projects/helm-operator/en/latest/guides/upgrading-to-ga.html).
+[here](https://docs.fluxcd.io/projects/helm-operator/en/latest/how-to/upgrade-to-ga/).
 
 ### Improvements
 
@@ -65,7 +65,7 @@ Please see the [install instruction](https://github.com/fluxcd/helm-operator/tre
 for Helm Operator v1.0.0. To keep using the same SSH key as Flux see the docs
 [here](https://github.com/fluxcd/helm-operator/tree/master/chart/helm-operator#use-fluxs-git-deploy-key).
 The upgrade procedure for `HelmReleases` from `v1beta1` to `v1` can be found
-[here](https://docs.fluxcd.io/projects/helm-operator/en/latest/guides/upgrading-to-ga.html).
+[here](https://docs.fluxcd.io/projects/helm-operator/en/latest/how-to/upgrade-to-ga/).
 
 ### Improvements
 

chart/flux/templates/NOTES.txt

@@ -3,7 +3,7 @@ Get the Git deploy key by either (a) running
   kubectl -n {{ .Release.Namespace }} logs deployment/{{ .Release.Name }} | grep identity.pub | cut -d '"' -f2
 
 or by (b) installing fluxctl through
-https://docs.fluxcd.io/en/latest/references/fluxctl.html#installing-fluxctl
+https://docs.fluxcd.io/en/latest/references/fluxctl#installing-fluxctl
 and running:
 
   fluxctl identity --k8s-fwd-ns {{ .Release.Namespace }}

deploy/flux-deployment.yaml

@@ -38,7 +38,7 @@ spec:
       # file, which you will need to do if you host your own git
       # repo rather than using github or the like. You'll also need to
       # mount it into the container, below. See
-      # https://docs.fluxcd.io/en/latest/guides/use-private-git-host.html
+      # https://docs.fluxcd.io/en/latest/guides/use-private-git-host
       # - name: ssh-config
       #   configMap:
       #     name: flux-ssh-config

docs/_static/custom.css

@@ -1,15 +1,24 @@
 @import url("https://fonts.googleapis.com/css?family=Montserrat&display=swap");
-@import url("https://fonts.googleapis.com/css?family=Roboto+Mono&display=swap");
 
 body {
   font-family: "Montserrat", sans-serif;
 }
 
-.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre {
-  font-family: "Roboto Mono", monospace;
+.md-logo {
+    width: 40px;
+    height: 40px;
+    padding-bottom: 2px;
+    padding-top: 2px;
+}
+.md-logo img {
+    width: 40px;
+    height: 40px;
 }
 
-code {
-  font-family: "Roboto Mono", monospace;
+.md-header, .md-footer-nav {
+    background-image: linear-gradient(45deg, rgb(0, 150, 225) 0%, rgb(27, 141, 226) 24%, rgb(42, 125, 227) 53%, rgb(53, 112, 227) 78%, rgb(53, 112, 227) 100%);
 }
 
+.md-header-nav__title {
+    font-size: .85rem;
+}