Skip to content

Commit e020c57

Browse files
james7132cart
andcommitted
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 <[email protected]>
1 parent 0529f63 commit e020c57

File tree

1 file changed

+53
-0
lines changed

1 file changed

+53
-0
lines changed

.github/workflows/docs.yml

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- 'main'
7+
8+
env:
9+
CARGO_TERM_COLOR: always
10+
RUSTDOCFLAGS: --html-in-header header.html
11+
12+
jobs:
13+
build-and-deploy:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout
17+
uses: actions/[email protected]
18+
19+
- name: Install Rust
20+
uses: actions-rs/toolchain@v1
21+
with:
22+
profile: minimal
23+
toolchain: stable
24+
override: true
25+
26+
# This does the following:
27+
# - Replaces the docs icon with one that clearly denotes it's not the released package on crates.io
28+
# - Adds a meta tag that forces Google not to index any page on the site.
29+
- name: Pre-docs-build
30+
run: |
31+
sed -i "s/icon.png/icon-docs-dev.png" src/lib.rs
32+
echo "<meta name=\"robots\" content=\"noindex\">" > header.html
33+
34+
- name: Build docs
35+
run: cargo doc --all-features --no-deps -p bevy
36+
37+
# This adds the following:
38+
# - A top level redirect to the bevy crate documentation
39+
# - A CNAME file for redirecting the docs domain to the API reference
40+
# - A robots.txt file to forbid any crawling of the site (to defer to the docs.rs site on search engines).
41+
# - A .nojekyll file to disable Jekyll GitHub Pages builds.
42+
- name: Finalize documentation
43+
run: |
44+
echo "<meta http-equiv=\"refresh\" content=\"0; url=bevy/index.html\">" > target/doc/index.html
45+
echo "dev-docs.bevyengine.org" > target/doc/CNAME
46+
echo "User-Agent: *\nDisallow: /" > target/doc/robots.txt
47+
touch target/doc/.nojekyll
48+
49+
- name: Deploy
50+
uses: JamesIves/[email protected]
51+
with:
52+
branch: gh-pages
53+
folder: target/doc

0 commit comments

Comments
 (0)