mirror of
https://github.com/bevyengine/bevy
synced 2024-12-01 08:59:11 +00:00
2012f13c05
# Objective - The [developer docs](https://dev-docs.bevyengine.org) are primarily used by developers, who often deal with internal and private functions. - @mweatherley suggested [on Discord](https://discord.com/channels/691052431525675048/743559241461399582/1273658470134186112) that CI passes `--document-private-items` to the dev-docs, so contributors can easily browse these internal details. ## Solution - Add `--document-private-items` to the CI job that builds the dev-docs. ## Testing - It should run in CI and generate documentation for private code. ## Drawbacks - Users that track the main branch may use the dev-docs instead of <https://docs.rs/bevy>, which may now show a lot of unwanted internal details. - Searching may be slower / bloated with internal details.
96 lines
3.2 KiB
YAML
96 lines
3.2 KiB
YAML
name: Deploy Docs
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- 'main'
|
|
# Allows running the action manually.
|
|
workflow_dispatch:
|
|
|
|
env:
|
|
CARGO_TERM_COLOR: always
|
|
RUSTDOCFLAGS: --html-in-header header.html
|
|
# If nightly is breaking CI, modify this variable to target a specific nightly version.
|
|
NIGHTLY_TOOLCHAIN: nightly
|
|
|
|
# Sets the permissions to allow deploying to Github pages.
|
|
permissions:
|
|
contents: read
|
|
pages: write
|
|
id-token: write
|
|
|
|
# Only allow one deployment to run at a time, however it will not cancel in-progress runs.
|
|
concurrency:
|
|
group: "pages"
|
|
cancel-in-progress: false
|
|
|
|
jobs:
|
|
build-and-deploy:
|
|
runs-on: ubuntu-latest
|
|
# Only run this job when on the main Bevy repository. Without this, it would also run on forks
|
|
# where developers work on the main branch but have not enabled Github Pages.
|
|
if: ${{ github.repository == 'bevyengine/bevy' }}
|
|
environment:
|
|
name: github-pages
|
|
url: ${{ steps.deployment.outputs.page_url }}
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
|
|
- uses: dtolnay/rust-toolchain@master
|
|
with:
|
|
toolchain: ${{ env.NIGHTLY_TOOLCHAIN }}
|
|
|
|
- name: Install Linux dependencies
|
|
uses: ./.github/actions/install-linux-deps
|
|
with:
|
|
wayland: true
|
|
xkb: 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.bak "s/icon.png/icon-docs-dev.png/" src/lib.rs
|
|
echo "<meta name=\"robots\" content=\"noindex\">" > header.html
|
|
|
|
- name: Build docs
|
|
env:
|
|
# needs to be in sync with [package.metadata.docs.rs]
|
|
RUSTFLAGS: --cfg docsrs_dep
|
|
RUSTDOCFLAGS: -Zunstable-options --cfg=docsrs --generate-link-to-definition
|
|
run: |
|
|
cargo doc \
|
|
-Zunstable-options \
|
|
-Zrustdoc-scrape-examples \
|
|
--all-features \
|
|
--workspace \
|
|
--no-deps \
|
|
--document-private-items \
|
|
--exclude ci \
|
|
--exclude errors \
|
|
--exclude bevy_mobile_example \
|
|
--exclude build-wasm-example \
|
|
--exclude build-templated-pages \
|
|
--exclude example-showcase
|
|
|
|
# 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).
|
|
- 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
|
|
rm target/doc/.lock
|
|
|
|
- name: Upload site artifact
|
|
uses: actions/upload-pages-artifact@v3
|
|
with:
|
|
path: target/doc
|
|
|
|
- name: Deploy to Github Pages
|
|
id: deployment
|
|
uses: actions/deploy-pages@v4
|