Skip to content

Commit

Permalink
Add automatic docs deployment to GitHub Pages (bevyengine#3535)
Browse files Browse the repository at this point in the history
# Objective

Partially address bevyengine#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 bevyengine#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 bevyengine#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>
  • Loading branch information
2 people authored and ItsDoot committed Feb 1, 2023
1 parent 0cbfd3c commit 00b0c02
Showing 1 changed file with 53 additions and 0 deletions.
53 changes: 53 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 00b0c02

Please sign in to comment.