Merge pull request #663 from external-secrets/feature/docs-versioning

Introducing Versioning to docs

.github/workflows/docs.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-
 env:
   # Common versions
   GO_VERSION: '1.17'
@@ -23,12 +22,6 @@ jobs:
           go-version: ${{ env.GO_VERSION }}
 
       - name: Build Docs
-        run: make docs
-
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3.8.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          cname: external-secrets.io
-          keep_files: true
+        run: make docs.publish
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.github/workflows/release.yml

@@ -54,6 +54,11 @@ jobs:
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 
+      - name: Update Docs
+        run: make docs.publish DOCS_VERSION=${{ github.event.inputs.version }} DOCS_ALIAS=latest
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+
   promote:
     name: Promote Container Image
     runs-on: ubuntu-latest

Makefile

@@ -190,6 +190,10 @@ helm.generate: helm.docs ## Copy crds to helm chart directory
 docs: generate ## Generate docs
 	$(MAKE) -C ./hack/api-docs build
 
+.PHONY: docs.publish
+docs.publish: generate ## Generate and deploys docs
+	$(MAKE) -C ./hack/api-docs build.publish
+
 .PHONY: serve-docs
 serve-docs: ## Serve docs
 	$(MAKE) -C ./hack/api-docs serve

docs/contributing-devguide.md

@@ -104,7 +104,7 @@ helm upgrade --install external-secrets ./deploy/charts/external-secrets/ --set
 
 ## Documentation
 
-We use [mkdocs material](https://squidfunk.github.io/mkdocs-material/) to generate this
+We use [mkdocs material](https://squidfunk.github.io/mkdocs-material/) and [mike](https://github.com/jimporter/mike) to generate this
 documentation. See `/docs` for the source code and `/hack/api-docs` for the build process.
 
 When writing documentation it is advised to run the mkdocs server with livereload:
@@ -121,3 +121,7 @@ make serve-docs
 ```
 
 Open `http://localhost:8000` in your browser.
+
+Since mike uses a branch to create/update documentation, any docs operation will create a diff on your local `gh-pages` branch.
+
+When finished writing/reviewing the docs, clean up your local docs branch changes with `git branch -D gh-pages`

docs/spec.md

@@ -714,237 +714,6 @@ string
 <td></td>
 </tr></tbody>
 </table>
-<h3 id="external-secrets.io/v1alpha1.ClusterExternalSecret">ClusterExternalSecret
-</h3>
-<p>
-<p>ClusterExternalSecret is the Schema for the clusterexternalsecrets API.</p>
-</p>
-<table>
-<thead>
-<tr>
-<th>Field</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-<code>metadata</code></br>
-<em>
-<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta">
-Kubernetes meta/v1.ObjectMeta
-</a>
-</em>
-</td>
-<td>
-Refer to the Kubernetes API documentation for the fields of the
-<code>metadata</code> field.
-</td>
-</tr>
-<tr>
-<td>
-<code>spec</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretSpec">
-ClusterExternalSecretSpec
-</a>
-</em>
-</td>
-<td>
-<br/>
-<br/>
-<table>
-<tr>
-<td>
-<code>externalSecretSpec</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ExternalSecretSpec">
-ExternalSecretSpec
-</a>
-</em>
-</td>
-<td>
-<p>The spec for the ExternalSecrets to be created</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>externalSecretName</code></br>
-<em>
-string
-</em>
-</td>
-<td>
-<em>(Optional)</em>
-<p>The name of the external secrets to be created defaults to the name of the ClusterExternalSecret</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>namespaceSelector</code></br>
-<em>
-<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#labelselector-v1-meta">
-Kubernetes meta/v1.LabelSelector
-</a>
-</em>
-</td>
-<td>
-<p>The labels to select by to find the Namespaces to create the ExternalSecrets in.</p>
-</td>
-</tr>
-</table>
-</td>
-</tr>
-<tr>
-<td>
-<code>status</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretStatus">
-ClusterExternalSecretStatus
-</a>
-</em>
-</td>
-<td>
-</td>
-</tr>
-</tbody>
-</table>
-<h3 id="external-secrets.io/v1alpha1.ClusterExternalSecretConditionType">ClusterExternalSecretConditionType
-(<code>string</code> alias)</p></h3>
-<p>
-(<em>Appears on:</em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretStatus">ClusterExternalSecretStatus</a>)
-</p>
-<p>
-</p>
-<table>
-<thead>
-<tr>
-<th>Value</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr><td><p>&#34;NotReady&#34;</p></td>
-<td></td>
-</tr><tr><td><p>&#34;PartiallyReady&#34;</p></td>
-<td></td>
-</tr><tr><td><p>&#34;Ready&#34;</p></td>
-<td></td>
-</tr></tbody>
-</table>
-<h3 id="external-secrets.io/v1alpha1.ClusterExternalSecretSpec">ClusterExternalSecretSpec
-</h3>
-<p>
-(<em>Appears on:</em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecret">ClusterExternalSecret</a>)
-</p>
-<p>
-<p>ClusterExternalSecretSpec defines the desired state of ClusterExternalSecret.</p>
-</p>
-<table>
-<thead>
-<tr>
-<th>Field</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-<code>externalSecretSpec</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ExternalSecretSpec">
-ExternalSecretSpec
-</a>
-</em>
-</td>
-<td>
-<p>The spec for the ExternalSecrets to be created</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>externalSecretName</code></br>
-<em>
-string
-</em>
-</td>
-<td>
-<em>(Optional)</em>
-<p>The name of the external secrets to be created defaults to the name of the ClusterExternalSecret</p>
-</td>
-</tr>
-<tr>
-<td>
-<code>namespaceSelector</code></br>
-<em>
-<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#labelselector-v1-meta">
-Kubernetes meta/v1.LabelSelector
-</a>
-</em>
-</td>
-<td>
-<p>The labels to select by to find the Namespaces to create the ExternalSecrets in.</p>
-</td>
-</tr>
-</tbody>
-</table>
-<h3 id="external-secrets.io/v1alpha1.ClusterExternalSecretStatus">ClusterExternalSecretStatus
-</h3>
-<p>
-(<em>Appears on:</em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecret">ClusterExternalSecret</a>)
-</p>
-<p>
-<p>ClusterExternalSecretStatus defines the observed state of ClusterExternalSecret.</p>
-</p>
-<table>
-<thead>
-<tr>
-<th>Field</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>
-<code>type</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretConditionType">
-ClusterExternalSecretConditionType
-</a>
-</em>
-</td>
-<td>
-</td>
-</tr>
-<tr>
-<td>
-<code>status</code></br>
-<em>
-<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#conditionstatus-v1-core">
-Kubernetes core/v1.ConditionStatus
-</a>
-</em>
-</td>
-<td>
-</td>
-</tr>
-<tr>
-<td>
-<code>externalSecretStatuses</code></br>
-<em>
-<a href="#external-secrets.io/v1alpha1.ExternalSecretStatus">
-[]ExternalSecretStatus
-</a>
-</em>
-</td>
-<td>
-<em>(Optional)</em>
-</td>
-</tr>
-</tbody>
-</table>
 <h3 id="external-secrets.io/v1alpha1.ClusterSecretStore">ClusterSecretStore
 </h3>
 <p>
@@ -1315,7 +1084,6 @@ string
 </h3>
 <p>
 (<em>Appears on:</em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretSpec">ClusterExternalSecretSpec</a>, 
 <a href="#external-secrets.io/v1alpha1.ExternalSecret">ExternalSecret</a>)
 </p>
 <p>
@@ -1403,7 +1171,6 @@ If multiple entries are specified, the Secret keys are merged in the specified o
 </h3>
 <p>
 (<em>Appears on:</em>
-<a href="#external-secrets.io/v1alpha1.ClusterExternalSecretStatus">ClusterExternalSecretStatus</a>, 
 <a href="#external-secrets.io/v1alpha1.ExternalSecret">ExternalSecret</a>)
 </p>
 <p>
@@ -1726,7 +1493,7 @@ map[string]string
 <a href="#external-secrets.io/v1alpha1.SecretStoreProvider">SecretStoreProvider</a>)
 </p>
 <p>
-<p>FakeProvider configures a fake provider that returns static values</p>
+<p>FakeProvider configures a fake provider that returns static values.</p>
 </p>
 <table>
 <thead>

hack/api-docs/Dockerfile

@@ -18,7 +18,12 @@ RUN apk add -U --no-cache \
     python3 \
     python3-dev \
     musl-dev \
+    git \
+    openssh \
+    git-fast-import \
     bash \
     gcc \
     diffutils \
-  && pip3 install -r /requirements.txt
+  && pip3 install -r /requirements.txt \
+  && git config --global user.email "docs@external-secrets.io" \
+  && git config --global user.name "Docs"

hack/api-docs/Makefile

@@ -15,6 +15,9 @@
 DOCKER ?= docker
 MKDOCS_IMAGE ?= github.com/external-secrets-mkdocs:latest
 MKDOCS ?= mkdocs
+MIKE ?= mike
+DOCS_VERSION ?= main
+DOCS_ALIAS ?= unstable
 SERVE_BIND_ADDRESS ?= 127.0.0.1
 
 # TOP is the current directory where this Makefile lives.
@@ -45,13 +48,23 @@ image:
 build: image generate $(SOURCES)
 	mkdir -p $(GENROOT)
 	$(DOCKER) run \
-		--mount type=bind,source=$(SRCDIR),target=/docs \
-		--mount type=bind,source=$(CFGFILE),target=/mkdocs.yml \
-		--mount type=bind,source=$(GENROOT),target=/site \
+	    --mount type=bind,source=$(ROOT),target=/repo \
 		--sig-proxy=true \
 		--rm \
+		--user $(UID):$(GID) \
 		$(MKDOCS_IMAGE) \
-		/bin/bash -c "cd / && $(MKDOCS) build; find /site -exec chown $(UID):$(GID) {} \;"
+		/bin/bash -c "cd /repo && $(MIKE) deploy --update-aliases -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
+
+.PHONY: build.publish
+build.publish: image generate $(SOURCES)
+	mkdir -p $(GENROOT)
+	$(DOCKER) run \
+	    --mount type=bind,source=$(ROOT),target=/repo \
+		--sig-proxy=true \
+		--rm \
+		--user $(UID):$(GID) \
+		$(MKDOCS_IMAGE) \
+		/bin/bash -c "cd /repo && $(MIKE) deploy --update-aliases -p -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
 
 .PHONY: generate
 generate:
@@ -64,14 +77,13 @@ clean:
 # serve runs mkdocs as a local webserver for interactive development.
 # This will serve the live copy of the docs on 127.0.0.1:8000.
 .PHONY: serve
-serve: build
+serve:
 	$(DOCKER) run \
 		-it \
 		--sig-proxy=true \
-		--mount type=bind,source=$(SRCDIR),target=/docs \
-		--mount type=bind,source=$(CFGFILE),target=/mkdocs.yml \
-		--mount type=bind,source=$(GENROOT),target=/site \
+	    --mount type=bind,source=$(ROOT),target=/repo \
+		--user $(UID):$(GID) \
 		-p $(SERVE_BIND_ADDRESS):8000:8000 \
 		--rm \
 		$(MKDOCS_IMAGE) \
-		/bin/bash -c "cd / && $(MKDOCS) serve -a 0.0.0.0:8000"
+		/bin/bash -c "cd /repo && $(MIKE) serve -F hack/api-docs/mkdocs.yml -a 0.0.0.0:8000"

hack/api-docs/mkdocs.yml

@@ -1,10 +1,12 @@
 site_name: External Secrets Operator
 repo_url: https://github.com/external-secrets/external-secrets
 repo_name: External Secrets Operator
-site_dir: site
-docs_dir: docs
+site_dir: ../../site
+docs_dir: ../../docs
+remote_branch: gh-pages
 theme:
   name: material
+  custom_dir: ../../overrides
 markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
@@ -17,6 +19,8 @@ plugins:
   - macros:
       include_dir: docs/snippets
 extra:
+  version:
+    provider: mike
   analytics:
     provider: google
     property: G-QP38TD8K7V

hack/api-docs/requirements.txt

@@ -1,16 +1,17 @@
 Click==7.0
 htmlmin==0.1.12
-Jinja2==2.10.3
+Jinja2==2.11.1
 jsmin==2.2.2
 livereload==2.6.1
 Markdown==3.2.1
 MarkupSafe==1.1.1
-mkdocs==1.1
-mkdocs-material==7.1.8
+mkdocs==1.2.3
+mike==1.1.2
+mkdocs-material==8.1.9
 mkdocs-minify-plugin==0.2.1
 pep562==1.0
-Pygments==2.5.2
-pymdown-extensions==7.0
+Pygments==2.10.0
+pymdown-extensions==9.0
 PyYAML==5.3
 six==1.14.0
 tornado==6.0.3

overrides/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}