From e020c572111e759e438c2c880b474b087bd78dc3 Mon Sep 17 00:00:00 2001
From: James Liu <contact@jamessliu.com>
Date: Tue, 15 Mar 2022 23:00:49 +0000
Subject: [PATCH] Add automatic docs deployment to GitHub Pages (#3535)

# Objective

Partially address #407 by setting up automated deployments of `bevy`'s API reference to GitHub Pages.

## Solution

Set up a GitHub Actions workflow that builds the docs on every push to `main` and pushes a new commit to a `gh-pages` (or `docs` branch).

A few smaller additions to better address #407:

 - A top level redirect was added to take "docs.bevyengine.org" directly to the `bevy` crate docs.
 - A GitHub Pages CNAME file for supporting a publicly viewable domain instead of `github.io`
 - A robots.txt file is added to disable all search engine crawlers that respect it from crawling it (avoid having conflicting Google search results)
 - A .nojekyl file to speed up deployments since there is no Jekyll templating in the output.

This may require configuration of the  `GITHUB_TOKEN` of the CI to successfully run this.

## Followup

For this to completely resolve #407, a subdomain of https://bevyengine.org/ needs to be set up to point to the CNAME location. This is initially set to "dev-docs.bevyengine.org".

Co-authored-by: Carter Anderson <mcanders1@gmail.com>
---
 .github/workflows/docs.yml | 53 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000000..e471a81330
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,53 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - 'main'
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTDOCFLAGS: --html-in-header header.html
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.1
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+
+      #  This does the following:
+      #   - Replaces the docs icon with one that clearly denotes it's not the released package on crates.io
+      #   - Adds a meta tag that forces Google not to index any page on the site.
+      - name: Pre-docs-build
+        run: |
+          sed -i "s/icon.png/icon-docs-dev.png" src/lib.rs
+          echo "<meta name=\"robots\" content=\"noindex\">" > header.html
+
+      - name: Build docs
+        run: cargo doc --all-features --no-deps -p bevy
+
+      #  This adds the following:
+      #   - A top level redirect to the bevy crate documentation
+      #   - A CNAME file for redirecting the docs domain to the API reference
+      #   - A robots.txt file to forbid any crawling of the site (to defer to the docs.rs site on search engines).
+      #   - A .nojekyll file to disable Jekyll GitHub Pages builds.
+      - name: Finalize documentation
+        run: |
+          echo "<meta http-equiv=\"refresh\" content=\"0; url=bevy/index.html\">" > target/doc/index.html
+          echo "dev-docs.bevyengine.org" > target/doc/CNAME
+          echo "User-Agent: *\nDisallow: /" > target/doc/robots.txt
+          touch target/doc/.nojekyll
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@4.1.7
+        with:
+          branch: gh-pages
+          folder: target/doc