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>
This commit is contained in:
		
							parent
							
								
									0529f633f9
								
							
						
					
					
						commit
						e020c57211
					
				
							
								
								
									
										53
									
								
								.github/workflows/docs.yml
									
									
									
									
										vendored
									
									
										Normal file
									
								
							
							
						
						
									
										53
									
								
								.github/workflows/docs.yml
									
									
									
									
										vendored
									
									
										Normal file
									
								
							| @ -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 | ||||||
		Loading…
	
		Reference in New Issue
	
	Block a user
	 James Liu
						James Liu