Better documentation build workflow from 2021 GA Hackathon

[epassaro]

Description

This is the documentation workflow I submitted to the 2021 GitHub Actions Hackathon.

It was designed to mimic ReadTheDocs behavior as much as possible. In this PR I present a simplified version, more suitable for TARDIS (since we are not going to use things like deploying SemVer tags, for example) and easier to understand.

Consists of two different workflows: build_docs.yml and clean_docs.yml.

Usage

Once merged, we can expect the following behavior:

• Changes to master will result in a new build of https://tardis-sn.github.io/tardis
• https://tardis-sn.github.io/tardis is redirected to https://tardis-sn.github.io/tardis/latest and latest could be changed to any word we want. Originally the word stable was reserved for the latest SemVer tag.
• Pull requests are deployed under https://tardis-sn.github.io/tardis/pull/number if the pull request is labeled with build-docs. Requires at least triage permissions.
• The @tardis-bot comment the result of PR builds with appropriate links - example
• Branches defined in the YAML file under the push trigger are deployed under https://tardis-sn.github.io/tardis/branch/branch-name
• Deleted branches and closed/merged pull requests builds are removed to keep the gh-pages branch tidy.

Motivation and context

A better/easier to understand documentation pipeline.

How has this been tested?

• Testing pipeline.
• Other.

Except for some minor details regarding to the TARDIS-specific implementation, these workflows were extensively tested since November 2021.

Notice this workflow uses the pull_request_target and this trigger can't be tested from this PR. Requires merging to see if it's working. You can see successful branch builds on my fork and a pull request example.

Examples

Type of change

• Bug fix.
• New feature.
• Breaking change.
• None of the above.

Checklist

• My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • (optional) I have built the documentation on my fork following the instructions.
• I have assigned and requested two reviewers for this pull request.

[codecov]

Codecov Report

Merging #1987 (9b8387a) into master (6983bfa) will not change coverage.
The diff coverage is n/a.

❗ Current head 9b8387a differs from pull request most recent head 9f8aada. Consider uploading reports for the commit 9f8aada to get more accurate results

@@           Coverage Diff           @@
##           master    #1987   +/-   ##
=======================================
  Coverage   59.99%   59.99%           
=======================================
  Files          70       70           
  Lines        8111     8111           
=======================================
  Hits         4866     4866           
  Misses       3245     3245           

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more