docs: fix deps, build & links warning (#6350)

* docs: fix deps, build & links warning

* fix ci

* add doc for local build

.github/workflows/docs.yaml

@@ -1,12 +1,13 @@
 name: Release Docs
 
 on:
-  push:
-    tags:
-      - "v*"
   # See https://docs.github.com/fr/webhooks/webhook-events-and-payloads#workflow_dispatch
   # Can be used to update doc with latest tag
   workflow_dispatch:
+    tag:
+      description: "Build documentation for specified tag value"
+      required: true
+      type: string
 
 permissions: {}
 
@@ -38,9 +39,6 @@ jobs:
 
       - name: build and push
         run: |
-          VERSION="${{ github.ref_name }}"
-          if [[ ${{ github.event_name }} == "workflow_dispatch" ]]; then
-            VERSION="latest"
-          fi
+          VERSION="${{ input.tag }}"
           mike deploy $VERSION --push --update-aliases
           mike set-default --push latest

CONTRIBUTING.md

@@ -14,7 +14,7 @@ We have full documentation on how to get started contributing here:
 
 ## Developer Documentation
 
-For more detailed contribution guides, see [Developer Documentation](docs/contributing) which includes:
+For more detailed contribution guides, see [Developer Documentation](docs/contributing/index.md) which includes:
 
 - [Development Guide](docs/contributing/dev-guide.md) - Setting up development environment, building, and testing
 - [Chart Development](docs/contributing/chart.md) - Working with Helm charts

docs/contributing/bug-report.md

@@ -176,7 +176,7 @@ aws route53 list-resource-record-sets \
 **external-dns info** — version, startup args, and logs:
 
 ```sh
-[[% include 'snippets/contributing/collect-extdns-info.sh' %]]
+[[% include 'contributing/collect-extdns-info.sh' %]]
 ```
 
 **Kubernetes resources** — set `RESOURCE` to the resource(s) relevant to your
@@ -184,7 +184,7 @@ source (e.g. `ingress`, `"ingress,service"`, `"gateway,httproute"`,
 `dnsendpoint`):
 
 ```sh
-[[% include 'snippets/contributing/collect-resources.sh' %]]
+[[% include 'contributing/collect-resources.sh' %]]
 ```
 
 ---

docs/contributing/dev-guide.md

@@ -224,7 +224,7 @@ go test ./tests/integration/...
 ## Complete test on local env
 
 It's possible to run ExternalDNS locally. CoreDNS can be used for easier testing.
-See the [related tutorials](../tutorials/coredns-etc.md) for full instructions.
+See the [related tutorials](../tutorials/coredns-etcd.md) for full instructions.
 
 ### Continuous Integration
 

docs/contributing/docs.md

@@ -0,0 +1,22 @@
+# Documentation
+
+## Tooling
+
+| Tool              | Documentation                       | Sources                           |
+|-------------------|-------------------------------------|-----------------------------------|
+| mkdocs            | [documentation][mkdocs]             | [Sources][mkdocs-src]             |
+
+[mkdocs]: https://www.mkdocs.org "Mkdocs"
+[mkdocs-src]: https://github.com/mkdocs/mkdocs "Mkdocs - Sources"
+
+## Build locally
+
+```sh
+# Pre-requisite: python3, pip and virtualenv
+DOCS="/tmp/extdns-docs"
+mkdir "$DOCS"
+virtualenv "$DOCS"
+source "$DOCS/bin/activate"
+pip install -r docs/scripts/requirements.txt
+mkdocs serve # or mkdocs build
+```

docs/scripts/requirements.txt

@@ -4,4 +4,5 @@ mkdocs-macros-plugin == 1.5.0
 mkdocs-material == 9.7.6
 mkdocs-literate-nav == 0.6.3
 mkdocs-same-dir == 0.1.4
+mdx-truly-sane-lists == 1.3
 mike == 2.1.4

docs/tutorials/azure-private-dns.md

@@ -118,7 +118,7 @@ This is per default done through the file `~/.kube/config`.
 For general background information on this see [kubernetes-docs](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/).
 Azure-CLI features functionality for automatically maintaining this file for AKS-Clusters. See [Azure-Docs](https://docs.microsoft.com/de-de/cli/azure/aks?view=azure-cli-latest#az-aks-get-credentials).
 
-Follow the steps for [azure-dns provider](./azure.md#creating-configuration-file) to create a configuration file.
+Follow the steps for [azure-dns provider](./azure.md#configuration-file) to create a configuration file.
 
 Then apply one of the following manifests depending on whether you use RBAC or not.
 

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
       - Monitoring: docs/monitoring/*
       - MultiTarget: docs/proposal/multi-target.md
       - NAT64: docs/advanced/nat64.md
+      - Operational Best Practices: docs/advanced/operational-best-practices.md
       - PTR Records: docs/advanced/ptr-records.md
       - Rate Limits: docs/advanced/rate-limits.md
       - TTL: docs/advanced/ttl.md