Workflow for automatic documentation creation and publishing

[renehernandez]

Description

Fixes #2562

This PR adds a workflow to automate publishing documentation using:

• Mkdocs: Building documentation
• Material for Mkdocs: Theming and features
• mike: to automate deployment and multiple version releases

You can see a running version of this documentation at https://renehernandez.github.io/external-dns/

Workflow details

• Runs on every new tag
• Publishes to gh-pages
• Will update the latest version to point to the new tag version, so we get automatic redirection
• Copies the CONTRIBUTING.md, code-of-conduct.md, LICENSE and README into the docs folder to make them available for the mkdocs build process
• Cleans the README/index.md to remove the docs/ prefix from the links. It is necessary since after copying into the docs folder the relative path are no longer correct

Other Changes

• Readme badges were modified into a single line, so they can show in a single line in the html generated by mkdocs
• Fix invalid link to UKFast_SafeDNS tutorial

Notes

• I am not publishing the proposal folder as part of the documentation, because it looks like the content is already out of date/implemented. I can add it if desired

Checklist

• Unit tests updated (Not applicable)
• End user documentation updated

[renehernandez]

/assign @seanmalloy

[renehernandez]

/assign @Raffo

[Raffo]

@renehernandez this looks very cool. Before I review this, can you fix the linting issue?

golangci/golangci-lint info installed /home/runner/go/bin/golangci-lint
>> checking license header
license header checking failed:
make: *** [Makefile:58: licensecheck] Error 1
./docs/scripts/docs.go
Error: Process completed with exit code 2.

[renehernandez]

@Raffo Update branch with latest master changes and fix the lint complains. Need you to approve again the workflows

[Raffo]

@renehernandez noob question: we are using github pages already for helm releases, would this conflict with that? Is there a way we can make both work? /cc @stevehipwell as well who's our helm expert.

[stevehipwell]

Based on the mike docs about special files it looks like existing files in the gh-pages branch wouldn't be modified. @renehernandez could you confirm that this is the case and has been tested?

Also I don't think that triggering the action on all tag pushes is correct, I assume that the docs need updating when ExternalDNS is released so the tags filter should be v* so as to not pick up chart releases etc.

[renehernandez]

@Raffo @stevehipwell I'll replicate the current github pages content in my fork and push a new version to confirm that it doesn't removed them.

I'll update the workflow to only run on tags prefixed with v

[renehernandez]

@Raffo @stevehipwell I've changed the docs workflow filter so it only runs on tags starting with v. Also verified that multiple docs releases do not remove content from the root of the repo in the gh-pages branch.

• gh-pages branch: https://github.com/renehernandez/external-dns/tree/gh-pages
• Actions runs: https://github.com/renehernandez/external-dns/actions
• Tags: https://github.com/renehernandez/external-dns/tags:
  • I have added external-dns-test tag an confirmed that the action wasn't triggered for it
  • Added multiple tags (v0.11.0-docs1, v0.11.0-docs2) and confirmed that the root content in gh-pages branch wasn't deleted

[Raffo]

@renehernandez thanks for the update, this is looking good! Please resolve the conflicts so that I can start CI again and we can give this a go, it will be a great addition.

[renehernandez]

@Raffo Fixed and ready to merge

[renehernandez]

@Raffo Bumping this again

[Raffo]

/approve
/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: Raffo, renehernandez

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [Raffo]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment