Merge pull request #2738 from kubernetes-sigs/revert-2727-revert-2652-documentation

Revert "Revert "Workflow for automatic documentation creation and publishing""
2025-11-04 12:41:00 +01:00 · 2022-05-06 01:29:08 -07:00 · 2022-05-06 01:29:08 -07:00 · 8fe105f2f5
commit 8fe105f2f5
parent 36396c58b9 afe3b09f45
9 changed files with 243 additions and 40 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@ -0,0 +1,43 @@
+name: Release Docs
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release_docs:
+    name: Release Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+          cache: "pip"
+          cache-dependency-path: "./docs/scripts/requirements.txt"
+
+      - uses: actions/setup-go@v2
+        with:
+          go-version: ^1.17
+
+      - 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"
+          git config --local user.name "github-actions[bot]"
+
+      - name: build and push
+        run: |
+          mike deploy ${{ github.ref_name }} latest --push --update-aliases
+          mike set-default --push latest
--- a/.gitignore
+++ b/.gitignore
@ -54,3 +54,10 @@ profile.cov

 # Helm charts
 !/charts/external-dns/
+
+docs/LICENSE.md
+docs/code-of-conduct.md
+docs/CONTRIBUTING.md
+docs/index.md
+docs/redirect
+site
--- a/README.md
+++ b/README.md
@ -1,13 +1,16 @@
+---
+hide:
+  - toc
+  - navigation
+---
+
 <p align="center">
-	<img src="img/external-dns.png" width="40%" align="center" alt="ExternalDNS">
+	<img src="docs/img/external-dns.png" width="40%" align="center" alt="ExternalDNS">
 </p>

 # ExternalDNS
-[![Build Status](https://github.com/kubernetes-sigs/external-dns/workflows/Go/badge.svg)](https://github.com/kubernetes-sigs/external-dns/actions)
-[![Coverage Status](https://coveralls.io/repos/github/kubernetes-sigs/external-dns/badge.svg)](https://coveralls.io/github/kubernetes-sigs/external-dns)
-[![GitHub release](https://img.shields.io/github/release/kubernetes-sigs/external-dns.svg)](https://github.com/kubernetes-sigs/external-dns/releases)
-[![go-doc](https://godoc.org/github.com/kubernetes-sigs/external-dns?status.svg)](https://godoc.org/github.com/kubernetes-sigs/external-dns)
-[![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/external-dns)](https://goreportcard.com/report/github.com/kubernetes-sigs/external-dns)
+
+[![Build Status](https://github.com/kubernetes-sigs/external-dns/workflows/Go/badge.svg)](https://github.com/kubernetes-sigs/external-dns/actions) [![Coverage Status](https://coveralls.io/repos/github/kubernetes-sigs/external-dns/badge.svg)](https://coveralls.io/github/kubernetes-sigs/external-dns) [![GitHub release](https://img.shields.io/github/release/kubernetes-sigs/external-dns.svg)](https://github.com/kubernetes-sigs/external-dns/releases) [![go-doc](https://godoc.org/github.com/kubernetes-sigs/external-dns?status.svg)](https://godoc.org/github.com/kubernetes-sigs/external-dns) [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes-sigs/external-dns)](https://goreportcard.com/report/github.com/kubernetes-sigs/external-dns)

 ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers.

@ -23,7 +26,7 @@ To see ExternalDNS in action, have a look at this [video](https://www.youtube.co

 ## The Latest Release

-ExternalDNS' allows you to keep selected zones (via `--domain-filter`) synchronized with Ingresses and Services of `type=LoadBalancer` and nodes in various cloud providers:
+ExternalDNS allows you to keep selected zones (via `--domain-filter`) synchronized with Ingresses and Services of `type=LoadBalancer` and nodes in various cloud providers:
 * [Google Cloud DNS](https://cloud.google.com/dns/docs/)
 * [AWS Route 53](https://aws.amazon.com/route53/)
 * [AWS Cloud Map](https://docs.aws.amazon.com/cloud-map/)
@ -77,38 +80,38 @@ We define the following stability levels for providers:

 The following table clarifies the current status of the providers according to the aforementioned stability levels:

-| Provider | Status | Maintainers |
-| -------- | ------ | ----------- |
-| Google Cloud DNS | Stable | |
-| AWS Route 53 | Stable | |
-| AWS Cloud Map | Beta | |
-| Akamai Edge DNS | Beta | |
-| AzureDNS | Beta | |
-| BlueCat | Alpha | @seanmalloy  @vinny-sabatini |
-| CloudFlare | Beta | |
-| RcodeZero | Alpha | |
-| DigitalOcean | Alpha | |
-| DNSimple | Alpha | |
-| Infoblox | Alpha | @saileshgiri |
-| Dyn | Alpha | |
-| OpenStack Designate | Alpha | |
-| PowerDNS | Alpha | |
-| CoreDNS | Alpha | |
-| Exoscale | Alpha | |
-| Oracle Cloud Infrastructure DNS | Alpha | |
-| Linode DNS | Alpha | |
-| RFC2136 | Alpha | |
-| NS1 | Alpha | |
-| TransIP | Alpha | |
-| VinylDNS | Alpha | |
-| RancherDNS | Alpha | |
-| OVH | Alpha | |
-| Scaleway DNS | Alpha | @Sh4d1 |
-| Vultr | Alpha | |
-| UltraDNS | Alpha | |
-| GoDaddy | Alpha | |
-| Gandi | Alpha | @packi |
-| SafeDNS | Alpha | @assureddt |
+| Provider                        | Status | Maintainers                  |
+| ------------------------------- | ------ | ---------------------------- |
+| Google Cloud DNS                | Stable |                              |
+| AWS Route 53                    | Stable |                              |
+| AWS Cloud Map                   | Beta   |                              |
+| Akamai Edge DNS                 | Beta   |                              |
+| AzureDNS                        | Beta   |                              |
+| BlueCat                         | Alpha  | @seanmalloy  @vinny-sabatini |
+| CloudFlare                      | Beta   |                              |
+| RcodeZero                       | Alpha  |                              |
+| DigitalOcean                    | Alpha  |                              |
+| DNSimple                        | Alpha  |                              |
+| Infoblox                        | Alpha  | @saileshgiri                 |
+| Dyn                             | Alpha  |                              |
+| OpenStack Designate             | Alpha  |                              |
+| PowerDNS                        | Alpha  |                              |
+| CoreDNS                         | Alpha  |                              |
+| Exoscale                        | Alpha  |                              |
+| Oracle Cloud Infrastructure DNS | Alpha  |                              |
+| Linode DNS                      | Alpha  |                              |
+| RFC2136                         | Alpha  |                              |
+| NS1                             | Alpha  |                              |
+| TransIP                         | Alpha  |                              |
+| VinylDNS                        | Alpha  |                              |
+| RancherDNS                      | Alpha  |                              |
+| OVH                             | Alpha  |                              |
+| Scaleway DNS                    | Alpha  | @Sh4d1                       |
+| Vultr                           | Alpha  |                              |
+| UltraDNS                        | Alpha  |                              |
+| GoDaddy                         | Alpha  |                              |
+| Gandi                           | Alpha  | @packi                       |
+| SafeDNS                         | Alpha  | @assureddt                   |

 ## Kubernetes version compatibility

@ -174,7 +177,7 @@ The following tutorials are provided:
 * [UltraDNS](docs/tutorials/ultradns.md)
 * [GoDaddy](docs/tutorials/godaddy.md)
 * [Gandi](docs/tutorials/gandi.md)
-* [SafeDNS](docs/tutorials/safedns.md)
+* [SafeDNS](docs/tutorials/UKFast_SafeDNS.md)
 * [Nodes as source](docs/tutorials/nodes.md)

 ### Running Locally
--- a/docs/img/external-dns.png
+++ b/docs/img/external-dns.png
--- a/docs/scripts/copy_docs.sh
+++ b/docs/scripts/copy_docs.sh
@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -eo pipefail
+
+cp CONTRIBUTING.md code-of-conduct.md ./docs/
+
+cp LICENSE ./docs/LICENSE.md
+
+cp README.md ./docs/index.md
--- a/docs/scripts/docs.go
+++ b/docs/scripts/docs.go
@ -0,0 +1,47 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"log"
+	"os"
+	"strings"
+)
+
+func removeLinkPrefixInIndex() {
+	content, err := os.ReadFile("./docs/index.md")
+	if err != nil {
+		log.Fatalf("Could not read index.md file. Make sure to run copy_docs.sh script first. Original error: %s", err)
+	}
+
+	updatedContent := strings.ReplaceAll(string(content), "](./docs/", "](")
+	updatedContent = strings.ReplaceAll(updatedContent, "](docs/", "](")
+
+	f, err := os.OpenFile("./docs/index.md", os.O_RDWR, 0644)
+	if err != nil {
+		log.Fatalf("Could not open index.md file to update content. Original error: %s", err)
+	}
+	defer f.Close()
+
+	if _, err := f.WriteString(updatedContent); err != nil {
+		log.Fatalf("Failed writing links update to index.md. Original error: %s", err)
+	}
+}
+
+func main() {
+	removeLinkPrefixInIndex()
+}
--- a/docs/scripts/index.html.gotmpl
+++ b/docs/scripts/index.html.gotmpl
@ -0,0 +1,3 @@
+<head>
+  <meta http-equiv="Refresh" content="0; url='/external-dns/{{.}}/'" />
+</head>
--- a/docs/scripts/requirements.txt
+++ b/docs/scripts/requirements.txt
@ -0,0 +1,5 @@
+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
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -0,0 +1,86 @@
+site_name: external-dns
+site_author: external-dns maintainers
+
+repo_name: kubernetes-sigs/external-dns
+repo_url: https://github.com/kubernetes-sigs/external-dns/
+
+nav:
+  - index.md
+  - Tutorials: tutorials/
+  - Advanced Topics:
+      - Initial Design: initial-design.md
+      - TTL: ttl.md
+  - Contributing:
+      - Kubernetes Contributions: CONTRIBUTING.md
+      - Release: release.md
+      - contributing/*
+  - About:
+      - FAQ: faq.md
+      - Out of Incubator: 20190708-external-dns-incubator.md
+      - Code of Conduct: code-of-conduct.md
+      - License: LICENSE.md
+
+theme:
+  name: material
+  features:
+    - content.code.annotate
+    - navigation.top
+    - navigation.tracking
+    - navigation.indexes
+    - navigation.instant
+    - navigation.tabs
+    - navigation.tabs.sticky
+
+extra:
+  version:
+    provider: mike
+
+markdown_extensions:
+  - meta
+  - tables
+  - toc:
+      permalink: true
+  - abbr
+  - extra
+  - admonition
+  - smarty
+  - sane_lists
+  - nl2br
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight:
+      use_pygments: true
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tilde
+  - pymdownx.tasklist:
+      custom_checkbox: true
+
+plugins:
+  - search
+  - literate-nav
+  - git-revision-date-localized:
+      type: date
+      fallback_to_build_date: true