From e1817f2cdc5fecc1daf4358887366f119d239bce Mon Sep 17 00:00:00 2001 From: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com> Date: Mon, 6 Apr 2026 15:15:29 +0200 Subject: [PATCH] docs: fix deps, build & links warning (#6350) * docs: fix deps, build & links warning * fix ci * add doc for local build --- .github/workflows/docs.yaml | 12 +++++------- CONTRIBUTING.md | 2 +- docs/contributing/bug-report.md | 4 ++-- docs/contributing/dev-guide.md | 2 +- docs/contributing/docs.md | 22 ++++++++++++++++++++++ docs/scripts/requirements.txt | 1 + docs/tutorials/azure-private-dns.md | 2 +- mkdocs.yml | 1 + 8 files changed, 34 insertions(+), 12 deletions(-) create mode 100644 docs/contributing/docs.md diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 891b29dd7..237f3eb6d 100644 --- a/.github/workflows/docs.yaml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fa5cbff3..feb7c628b 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/docs/contributing/bug-report.md b/docs/contributing/bug-report.md index 3e49acd38..ddb9ddd6f 100644 --- a/docs/contributing/bug-report.md +++ b/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' %]] ``` --- diff --git a/docs/contributing/dev-guide.md b/docs/contributing/dev-guide.md index 6520831fd..e689e4f78 100644 --- a/docs/contributing/dev-guide.md +++ b/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 diff --git a/docs/contributing/docs.md b/docs/contributing/docs.md new file mode 100644 index 000000000..5f83a7a4c --- /dev/null +++ b/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 +``` diff --git a/docs/scripts/requirements.txt b/docs/scripts/requirements.txt index 27a261f75..66d296487 100644 --- a/docs/scripts/requirements.txt +++ b/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 diff --git a/docs/tutorials/azure-private-dns.md b/docs/tutorials/azure-private-dns.md index c0c543726..d1b01dd7d 100644 --- a/docs/tutorials/azure-private-dns.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index a7c634844..59256e2a8 100644 --- a/mkdocs.yml +++ b/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