NDG Documentation #55
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: NDG Documentation | |
| on: | |
| workflow_dispatch: | |
| pull_request: | |
| branches: [main] | |
| workflow_run: | |
| workflows: ["Build and Test with Cargo"] # must match the `name:` of rust.yml exactly | |
| types: | |
| - completed | |
| permissions: | |
| contents: write | |
| env: | |
| CARGO_INCREMENTAL: 0 | |
| CARGO_NET_RETRY: 10 | |
| RUSTUP_MAX_RETRIES: 10 | |
| CARGO_TERM_COLOR: always | |
| jobs: | |
| pages: | |
| if: ${{ github.event.workflow_run.conclusion == 'success' }} | |
| continue-on-error: false | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout Repository | |
| uses: actions/checkout@v6 | |
| - name: Install Rust Toolchain | |
| uses: dtolnay/rust-toolchain@nightly | |
| - name: Restore Cache | |
| uses: Swatinem/rust-cache@v2 | |
| with: | |
| cache-targets: true | |
| cache-on-failure: true | |
| - name: Cache NDG Binary | |
| id: cache-ndg | |
| uses: actions/cache@v5 | |
| with: | |
| path: target/release/ndg | |
| key: ndg-binary-${{ runner.os }}-${{ hashFiles('Cargo.lock', '**/Cargo.toml', 'ndg/src/**', 'ndg-commonmark/src/**') }} | |
| restore-keys: | | |
| ndg-binary-${{ runner.os }}- | |
| - name: Build Rust Documentation | |
| run: | | |
| # Build documentation for public workspace members. This will create | |
| # the API documentation in target/doc with examples scraped as per | |
| # the unstable cargo option. | |
| # See: | |
| # <https://doc.rust-lang.org/rustdoc/scraped-examples.html> | |
| cargo doc --workspace --exclude xtask --no-deps \ | |
| --document-private-items -Zunstable-options -Zrustdoc-scrape-examples | |
| - name: Build NDG Binary | |
| if: steps.cache-ndg.outputs.cache-hit != 'true' | |
| run: cargo build --release -p ndg | |
| - name: Generate NDG Documentation | |
| run: | | |
| # We want to use NDG's readme in the index, so we should copy it | |
| cp -rvf ./ndg/README.md ./ndg/docs/index.md # index.md so it's the first entry | |
| # Generate NDG's own documentation using NDG itself | |
| ./target/release/ndg --config-file .github/ndg.toml html | |
| - name: Prepare GitHub Pages Deployment | |
| run: | | |
| # - ndg.feel-co.org/ -> NDG user documentation | |
| # - ndg.feel-co.org/api/ -> Rustdoc API documentation | |
| mkdir -p ./deploy | |
| mv ./build/* ./deploy/ | |
| mv ./target/doc ./deploy/api | |
| # Create index redirect for API documentation | |
| echo '<meta http-equiv="Refresh" content="0; url=ndg_commonmark/" />' > ./deploy/api/index.html | |
| - name: Deploy Docs | |
| uses: JamesIves/github-pages-deploy-action@v4 | |
| with: | |
| folder: ./deploy | |
| branch: gh-pages | |
| clean: false # keep existing files, i.e., badges | |