Merge pull request #4378 from mloiseleur/docs/upgrade-mkdocs

docs: upgrade mkdocs and fix broken links
kubernetes-sigs · Jun 11, 2024 · b84fc93 · b84fc93
2 parents 618b8df + 86b862c
commit b84fc93
Show file tree

Hide file tree

Showing 14 changed files with 62 additions and 106 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -6,6 +6,7 @@ on:
       - "v*"
 
 permissions: {}
+
 jobs:
   release_docs:
     permissions:
@@ -18,24 +19,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5.1.0
+      - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.12"
           cache: "pip"
           cache-dependency-path: "./docs/scripts/requirements.txt"
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
         with:
-          go-version: '^1.22.4'
+          go-version-file: 'go.mod'
 
       - run: |
           pip install -r docs/scripts/requirements.txt
 
-      - name: setup
-        run: |
-          ./docs/scripts/copy_docs.sh
-          go run ./docs/scripts/docs.go
-
       - name: Configure Git user
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"

diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
diff --git a/README.md b/README.md
@@ -15,6 +15,10 @@ hide:
 
 ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers.
 
+## Documentation
+
+This README is a part of the complete documentation, available [here](https://kubernetes-sigs.github.io/external-dns/).
+
 ## What It Does
 
 Inspired by [Kubernetes DNS](https://github.com/kubernetes/dns), Kubernetes' cluster-internal DNS server, ExternalDNS makes Kubernetes resources discoverable via public DNS servers. Like KubeDNS, it retrieves a list of resources (Services, Ingresses, etc.) from the [Kubernetes API](https://kubernetes.io/docs/api/) to determine a desired list of DNS records. *Unlike* KubeDNS, however, it's not a DNS server itself, but merely configures other DNS providers accordingly—e.g. [AWS Route 53](https://aws.amazon.com/route53/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/).
@@ -206,7 +210,7 @@ The following tutorials are provided:
 * [UltraDNS](docs/tutorials/ultradns.md)
 * [GoDaddy](docs/tutorials/godaddy.md)
 * [Gandi](docs/tutorials/gandi.md)
-* [SafeDNS](docs/tutorials/UKFast_SafeDNS.md)
+* [SafeDNS](docs/tutorials/ANS_Group_SafeDNS.md)
 * [IBM Cloud](docs/tutorials/ibmcloud.md)
 * [Nodes as source](docs/tutorials/nodes.md)
 * [TencentCloud](docs/tutorials/tencentcloud.md)
@@ -278,7 +282,7 @@ Now you can experiment and watch how ExternalDNS makes sure that your DNS record
 * Add another Service to create more DNS records.
 * Remove Services to clean up your managed zone.
 
-The [tutorials](docs/tutorials) section contains examples, including Ingress resources, and shows you how to set up ExternalDNS in different environments such as other cloud providers and alternative Ingress controllers.
+The **tutorials** section contains examples, including Ingress resources, and shows you how to set up ExternalDNS in different environments such as other cloud providers and alternative Ingress controllers.
 
 # Note
 

diff --git a/docs/contributing/getting-started.md b/docs/contributing/getting-started.md
@@ -29,17 +29,17 @@ make build.push IMAGE=your-registry/external-dns
 
 # Design
 
-ExternalDNS's sources of DNS records live in package [source](../../source). They implement the `Source` interface that has a single method `Endpoints` which returns the represented source's objects converted to `Endpoints`. Endpoints are just a tuple of DNS name and target where target can be an IP or another hostname.
+ExternalDNS's sources of DNS records live in package [source](https://github.com/kubernetes-sigs/external-dns/tree/master/source). They implement the `Source` interface that has a single method `Endpoints` which returns the represented source's objects converted to `Endpoints`. Endpoints are just a tuple of DNS name and target where target can be an IP or another hostname.
 
 For example, the `ServiceSource` returns all Services converted to `Endpoints` where the hostname is the value of the `external-dns.alpha.kubernetes.io/hostname` annotation and the target is the IP of the load balancer or where the hostname is the value of the `external-dns.alpha.kubernetes.io/internal-hostname` annotation and the target is the IP of the service ClusterIP.
 
-This list of endpoints is passed to the [Plan](../../plan) which determines the difference between the current DNS records and the desired list of `Endpoints`.
+This list of endpoints is passed to the [Plan](https://github.com/kubernetes-sigs/external-dns/tree/master/plan) which determines the difference between the current DNS records and the desired list of `Endpoints`.
 
-Once the difference has been figured out the list of intended changes is passed to a `Registry` which live in the [registry](../../registry) package. The registry is a wrapper and access point to DNS provider. Registry implements the ownership concept by marking owned records and filtering out records not owned by ExternalDNS before passing them to DNS provider.
+Once the difference has been figured out the list of intended changes is passed to a `Registry` which live in the [registry](https://github.com/kubernetes-sigs/external-dns/tree/master/registry) package. The registry is a wrapper and access point to DNS provider. Registry implements the ownership concept by marking owned records and filtering out records not owned by ExternalDNS before passing them to DNS provider.
 
-The [provider](../../provider) is the adapter to the DNS provider, e.g. Google Cloud DNS. It implements two methods: `ApplyChanges` to apply a set of changes filtered by `Registry` and `Records` to retrieve the current list of records from the DNS provider.
+The [provider](https://github.com/kubernetes-sigs/external-dns/tree/master/provider) is the adapter to the DNS provider, e.g. Google Cloud DNS. It implements two methods: `ApplyChanges` to apply a set of changes filtered by `Registry` and `Records` to retrieve the current list of records from the DNS provider.
 
-The orchestration between the different components is controlled by the [controller](../../controller).
+The orchestration between the different components is controlled by the [controller](https://github.com/kubernetes-sigs/external-dns/tree/master/controller).
 
 You can pick which `Source` and `Provider` to use at runtime via the `--source` and `--provider` flags, respectively.
 

diff --git a/docs/faq.md b/docs/faq.md
@@ -273,7 +273,7 @@ spec:
 Sometimes you need to run an internal and an external dns service.
 The internal one should provision hostnames used on the internal network (perhaps inside a VPC), and the external one to expose DNS to the internet.
 
-To do this with ExternalDNS you can use the `--ingress-class` flag to specifically tie an instance of ExternalDNS to an instance of a ingress controller. 
+To do this with ExternalDNS you can use the `--ingress-class` flag to specifically tie an instance of ExternalDNS to an instance of a ingress controller.
 Let's assume you have two ingress controllers, `internal` and `external`.
 You can then start two ExternalDNS providers, one with `--ingress-class=internal` and one with `--ingress-class=external`.
 
@@ -295,8 +295,8 @@ Note: the `--ingress-class` flag cannot be used at the same time as the `--annot
 **Performance considerations**
 
 Filtering based on ingress class name or annotations means that the external-dns controller will receive all resources of that kind and then filter on the client-side.
-In larger clusters with many resources which change frequently this can cause performance issues. 
-If only some resources need to be managed by an instance of external-dns then label filtering can be used instead of ingress class filtering (or legacy annotation filtering). 
+In larger clusters with many resources which change frequently this can cause performance issues.
+If only some resources need to be managed by an instance of external-dns then label filtering can be used instead of ingress class filtering (or legacy annotation filtering).
 This means that only those resources which match the selector specified in `--label-filter` will be passed to the controller.
 
 ### How do I specify that I want the DNS record to point to either the Node's public or private IP when it has both?
@@ -331,7 +331,7 @@ registry.k8s.io/external-dns/external-dns
 
 As tags, you use the external-dns release of choice(i.e. `v0.7.6`). A `latest` tag is not provided in the container registry.
 
-If you wish to build your own image, you can use the provided [.ko.yaml](../.ko.yaml) as a starting point.
+If you wish to build your own image, you can use the provided [.ko.yaml](https://github.com/kubernetes-sigs/external-dns/blob/master/.ko.yaml) as a starting point.
 
 ### Which architectures are supported?
 

diff --git a/docs/scripts/copy_docs.sh b/docs/scripts/copy_docs.sh
diff --git a/docs/scripts/docs.go b/docs/scripts/docs.go
diff --git a/docs/scripts/requirements.txt b/docs/scripts/requirements.txt
@@ -1,5 +1,6 @@
-mkdocs-git-revision-date-localized-plugin == 1.0.0
-mkdocs == 1.3.0
-mkdocs-material == 8.2.8
-mkdocs-literate-nav == 0.4.0
-mike == 1.1.2
+mkdocs-git-revision-date-localized-plugin == 1.2.4
+mkdocs == 1.5.3
+mkdocs-material == 9.5.17
+mkdocs-literate-nav == 0.6.1
+mkdocs-same-dir == 0.1.3
+mike == 2.0.0
diff --git a/docs/tutorials/aws.md b/docs/tutorials/aws.md
@@ -878,7 +878,7 @@ Note: ExternalDNS does not support creating healthchecks, and assumes that `<hea
 
 When creating ALIAS type records in Route53 it is required that external-dns be aware of the canonical hosted zone in which
 the specified hostname is created. External-dns is able to automatically identify the canonical hosted zone for many
-hostnames based upon known hostname suffixes which are defined in [aws.go](../../provider/aws/aws.go). If a hostname
+hostnames based upon known hostname suffixes which are defined in [aws.go](https://github.com/kubernetes-sigs/external-dns/blob/master/provider/aws/aws.go#L65). If a hostname
 does not have a known suffix then the suffix can be added into `aws.go` or the [target-hosted-zone annotation](#target-hosted-zone)
 can be used to manually define the ID of the canonical hosted zone.
 

diff --git a/docs/tutorials/mx-record.md b/docs/tutorials/mx-record.md
@@ -1,6 +1,6 @@
 # Creating MX record with CRD source
 
-You can create and manage MX records with the help of [CRD source](/docs/contributing/crd-source.md)
+You can create and manage MX records with the help of [CRD source](../contributing/crd-source.md)
 and `DNSEndpoint` CRD. Currently, this feature is only supported by `aws`, `azure`, and `google` providers.
 
 In order to start managing MX records you need to set the `--managed-record-types MX` flag.

diff --git a/docs/tutorials/ns-record.md b/docs/tutorials/ns-record.md
@@ -1,6 +1,6 @@
 # Creating NS record with CRD source
 
-You can create NS records with the help of [CRD source](/docs/contributing/crd-source.md)
+You can create NS records with the help of [CRD source](../contributing/crd-source.md)
 and `DNSEndpoint` CRD.
 
 Consider the following example

diff --git a/docs/tutorials/webhook-provider.md b/docs/tutorials/webhook-provider.md
@@ -43,7 +43,7 @@ Custom annotations can be used to influence DNS record creation and updates. Pro
 
 ## Provider registry
 
-To simplify the discovery of providers, we will accept pull requests that will add links to providers in the [README](../../README.md) file. This list will only serve the purpose of simplifying finding providers and will not constitute an official endorsement of any of the externally implemented providers unless otherwise stated.
+To simplify the discovery of providers, we will accept pull requests that will add links to providers in this documentation. This list will only serve the purpose of simplifying finding providers and will not constitute an official endorsement of any of the externally implemented providers unless otherwise stated.
 
 ## Run an ExternalDNS in-tree provider as a webhook.
 

diff --git a/external-dns.code-workspace b/external-dns.code-workspace
@@ -0,0 +1,7 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	]
+}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,37 +1,41 @@
 site_name: external-dns
 site_author: external-dns maintainers
-
 repo_name: kubernetes-sigs/external-dns
 repo_url: https://github.com/kubernetes-sigs/external-dns/
-
 trademark: https://www.linuxfoundation.org/legal/trademark-usage
 
+docs_dir: .
+
 nav:
-  - index.md
+  - README.md
+  - Chart:
+      - About: charts/external-dns/README.md
+      - Changelog: charts/external-dns/CHANGELOG.md
   - About:
-      - FAQ: faq.md
-      - Out of Incubator: 20190708-external-dns-incubator.md
+      - FAQ: docs/faq.md
+      - Out of Incubator: docs/20190708-external-dns-incubator.md
       - Code of Conduct: code-of-conduct.md
       - License: LICENSE.md
-  - Tutorials: tutorials/
+  - Tutorials: docs/tutorials/*
   - Annotations:
-    - About: annotations/annotations.md
+    - About: docs/annotations/annotations.md
   - Sources:
-    - About: sources/sources.md
-    - Gateway: sources/gateway.md
-    - Ingress: sources/ingress.md
-    - Service: sources/service.md
+    - About: docs/sources/sources.md
+    - Gateway: docs/sources/gateway.md
+    - Ingress: docs/sources/ingress.md
+    - Service: docs/sources/service.md
   - Registries:
-    - About: registry/registry.md
-    - TXT: registry/txt.md
-    - DynamoDB: registry/dynamodb.md
+    - About: docs/registry/registry.md
+    - TXT: docs/registry/txt.md
+    - DynamoDB: docs/registry/dynamodb.md
   - Advanced Topics:
-      - Initial Design: initial-design.md
-      - TTL: ttl.md
+      - Initial Design: docs/initial-design.md
+      - TTL: docs/ttl.md
+      - MultiTarget: docs/proposal/multi-target.md
   - Contributing:
       - Kubernetes Contributions: CONTRIBUTING.md
-      - Release: release.md
-      - contributing/*
+      - Release: docs/release.md
+      - docs/contributing/*
 
 theme:
   name: material
@@ -71,8 +75,8 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight:
       use_pygments: true
       anchor_linenums: true
@@ -93,6 +97,7 @@ markdown_extensions:
       custom_checkbox: true
 
 plugins:
+  - same-dir
   - search
   - literate-nav
   - git-revision-date-localized: