This file contains 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: Automate Documentation Build #name of action | |
| on: #trigger event | |
| push: | |
| branches: | |
| - bug/gha-docs-fix #execute on a push to master branch | |
| permissions: | |
| contents: write #grant access to write to master branch | |
| jobs: #define set of jobs. Here there is only one job, each job is instantiated on a Github-hosted runner | |
| docs: #name of the job | |
| runs-on: ubuntu-latest #runner runs on latest version of Ubuntu | |
| steps: #this job is associated with a series of steps | |
| # step 1: syntax for telling GHA to use this repository's code as "root" directory. Rest of GHA is able to have access | |
| - uses: actions/checkout@v3 | |
| with: | |
| fetch-depth: 0 | |
| # step 2: #syntax for telling GHA to set-up Python on this runner associated for this whole job | |
| - uses: actions/setup-python@v3 | |
| # Step 3: define a step that install dependencies (Sphinx etc) for this runner | |
| - name: Install dependencies #name of this step | |
| run: | #indicate that following script is meant to be multi-line | |
| pip install sphinx sphinx_rtd_theme myst_parser | |
| # Step 4: Build docs using sphinx. TZ=UTC needed to circumvent a nuance of running Sphinx on GHA runner | |
| - name: Sphinx build | |
| run: | | |
| cd docs | |
| TZ=UTC sphinx-build source build | |
| ls | |
| # Step 5: Deploy the newly built docs to gh-pages branch | |
| - name: Deploy to GitHub Pages | |
| #uses a github action "extension" called actions-gh-pages | |
| uses: peaceiris/actions-gh-pages@v3 | |
| #if: github.ref == 'refs/heads/bug/gha-docs-fix' #ensure that we are on the master branch | |
| #fooe | |
| #following is syntax for using actions-gh-pages action | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: ./docs/build | |
| keep_files: true | |
| # Step 4: Build docs using sphinx. TZ=UTC needed to circumvent a nuance of running Sphinx on GHA runner | |
| - name: Fix gh-pages directory structure | |
| run: | | |
| cd .. | |
| ls | |
| cd gh-pages | |
| mkdir docs | |
| cp -r html docs | |