Add Sphinx autodoc and GitHub pages #1
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
| # Deploy Sphinx. This could be shorter, but we also do some extra | |
| # stuff. | |
| # | |
| # License: CC-0. This is the canonical location of this file, which | |
| # you may want to link to anyway: | |
| # https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml | |
| # https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml | |
| name: sphinx | |
| on: [push, pull_request] | |
| env: | |
| DEFAULT_BRANCH: "master" | |
| # If these SPHINXOPTS are enabled, then be strict about the | |
| # builds and fail on any warnings. | |
| #SPHINXOPTS: "-W --keep-going -T" | |
| GENERATE_PDF: false # to enable, must be 'true' lowercase | |
| GENERATE_SINGLEHTML: false # to enable, must be 'true' lowercase | |
| PDF_FILENAME: lesson.pdf | |
| MULTIBRANCH: false # to enable, must be 'true' lowercase | |
| jobs: | |
| build: | |
| name: Build | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: read | |
| steps: | |
| # https://github.com/marketplace/actions/checkout | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| lfs: true | |
| # https://github.com/marketplace/actions/setup-python | |
| # ^-- This gives info on matrix testing. | |
| - name: Install Python | |
| uses: actions/setup-python@v3 | |
| # with: | |
| # python-version: '3.11' | |
| # cache: 'pip' | |
| # https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies | |
| # ^-- This gives info on installing dependencies with pip | |
| - name: Install dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| if [ -f requirements.txt ]; then pip install -r requirements.txt; fi | |
| python -m pip install sphinx numpy scipy matplotlib scikit-image numba yt geopack # add versions to matrix | |
| # Debug | |
| - name: Debugging information | |
| env: | |
| ref: ${{github.ref}} | |
| event_name: ${{github.event_name}} | |
| head_ref: ${{github.head_ref}} | |
| base_ref: ${{github.base_ref}} | |
| run: | | |
| echo "github.ref: ${ref}" | |
| echo "github.event_name: ${event_name}" | |
| echo "github.head_ref: ${head_ref}" | |
| echo "github.base_ref: ${base_ref}" | |
| echo "GENERATE_PDF: ${GENERATE_PDF}" | |
| echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}" | |
| set -x | |
| git rev-parse --abbrev-ref HEAD | |
| git branch | |
| git branch -a | |
| git remote -v | |
| python -V | |
| pip list --not-required | |
| pip list | |
| # Build | |
| - uses: ammaraskar/sphinx-problem-matcher@master | |
| - name: Build Sphinx docs (dirhtml) | |
| # SPHINXOPTS used via environment variables | |
| run: | | |
| cd Documentation/sphinx/ | |
| make dirhtml | |
| # This fixes broken copy button icons, as explained in | |
| # https://github.com/coderefinery/sphinx-lesson/issues/50 | |
| # https://github.com/executablebooks/sphinx-copybutton/issues/110 | |
| # This can be removed once these PRs are accepted (but the | |
| # fixes also need to propagate to other themes): | |
| # https://github.com/sphinx-doc/sphinx/pull/8524 | |
| # https://github.com/readthedocs/sphinx_rtd_theme/pull/1025 | |
| sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true | |
| # singlehtml | |
| - name: Generate singlehtml | |
| if: ${{ env.GENERATE_SINGLEHTML == 'true' }} | |
| run: | | |
| make singlehtml | |
| mv _build/singlehtml/ _build/dirhtml/singlehtml/ | |
| # PDF if requested | |
| - name: Generate PDF | |
| if: ${{ env.GENERATE_PDF == 'true' }} | |
| run: | | |
| pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip | |
| make pyppeteer | |
| mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME} | |
| # Stage all deployed assets in _gh-pages/ for simplicity, and to | |
| # prepare to do a multi-branch deployment. | |
| - name: Copy deployment data to _gh-pages/ | |
| if: ${{ github.event_name == 'push' }} | |
| run: | |
| rsync -a Documentation/sphinx/_build/dirhtml/ _gh-pages/ | |
| # Use gh-pages-multibranch to multiplex different branches into | |
| # one deployment. See | |
| # https://github.com/coderefinery/gh-pages-multibranch | |
| - name: gh-pages multibranch | |
| uses: coderefinery/gh-pages-multibranch@main | |
| if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }} | |
| with: | |
| directory: _gh-pages/ | |
| default_branch: ${{ env.DEFAULT_BRANCH }} | |
| publish_branch: gh-pages | |
| # Add the .nojekyll file | |
| - name: nojekyll | |
| if: ${{ github.event_name == 'push' }} | |
| run: | | |
| touch _gh-pages/.nojekyll | |
| # Save artifact for the next step. | |
| - uses: actions/upload-artifact@v4 | |
| if: ${{ github.event_name == 'push' }} | |
| with: | |
| name: gh-pages-build | |
| path: _gh-pages/ | |
| # Deploy in a separate job so that write permissions are restricted | |
| # to the minimum steps. | |
| deploy: | |
| name: Deploy | |
| runs-on: ubuntu-latest | |
| needs: build | |
| # This if can't use the env context - find better way later. | |
| if: ${{ github.event_name == 'push' }} | |
| permissions: | |
| contents: write | |
| steps: | |
| - uses: actions/download-artifact@v4 | |
| if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} | |
| with: | |
| name: gh-pages-build | |
| path: _gh-pages/ | |
| # As of 2023, we could publish to pages via a Deployment. This | |
| # isn't done yet to give it time to stabilize (out of beta), and | |
| # also having a gh-pages branch to check out is rather | |
| # convenient. | |
| # Deploy | |
| # https://github.com/peaceiris/actions-gh-pages | |
| - name: Deploy | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }} | |
| with: | |
| publish_branch: gh-pages | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| publish_dir: _gh-pages/ | |
| force_orphan: true |