Replace sphinx napoleon for numpydoc #390
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
| # Build the documentation and deploy to GitHub Pages using GitHub Actions. | |
| # | |
| # NOTE: Pin actions to a specific commit to avoid having the authentication | |
| # token stolen if the Action is compromised. See the comments and links here: | |
| # https://github.com/pypa/gh-action-pypi-publish/issues/27 | |
| # | |
| name: docs | |
| # Only build PRs, the main branch, and releases. Pushes to branches will only | |
| # be built when a PR is opened. This avoids duplicated buids in PRs comming | |
| # from branches in the origin repository (1 for PR and 1 for push). | |
| on: | |
| pull_request: | |
| push: | |
| branches: | |
| - main | |
| release: | |
| types: | |
| - published | |
| # Use bash by default in all jobs | |
| defaults: | |
| run: | |
| # The -l {0} is necessary for conda environments to be activated | |
| # But this breaks on MacOS if using actions/setup-python: | |
| # https://github.com/actions/setup-python/issues/132 | |
| shell: bash -l {0} | |
| jobs: | |
| ############################################################################# | |
| # Build the docs | |
| build: | |
| runs-on: ubuntu-latest | |
| env: | |
| REQUIREMENTS: env/requirements-docs.txt env/requirements-build.txt | |
| PYTHON: "3.12" | |
| steps: | |
| # Checks-out your repository under $GITHUB_WORKSPACE | |
| - name: Checkout | |
| uses: actions/checkout@v4.1.6 | |
| with: | |
| # Need to fetch more than the last commit so that setuptools-scm can | |
| # create the correct version string. If the number of commits since | |
| # the last release is greater than this, the version still be wrong. | |
| # Increase if necessary. | |
| fetch-depth: 100 | |
| # The GitHub token is preserved by default but this job doesn't need | |
| # to be able to push to GitHub. | |
| persist-credentials: false | |
| # Need the tags so that setuptools-scm can form a valid version number | |
| - name: Fetch git tags | |
| run: git fetch origin 'refs/tags/*:refs/tags/*' | |
| - name: Setup Miniconda | |
| uses: conda-incubator/setup-miniconda@v3 | |
| with: | |
| python-version: ${{ env.PYTHON }} | |
| channels: conda-forge,defaults | |
| - name: Collect requirements | |
| run: | | |
| echo "Install Dependente to capture dependencies:" | |
| python -m pip install dependente==0.3.0 | |
| echo "" | |
| echo "Capturing run-time dependencies:" | |
| dependente --source install > requirements-full.txt | |
| echo "" | |
| echo "Capturing dependencies from:" | |
| for requirement in $REQUIREMENTS | |
| do | |
| echo " $requirement" | |
| cat $requirement >> requirements-full.txt | |
| done | |
| echo "" | |
| echo "Collected dependencies:" | |
| cat requirements-full.txt | |
| - name: Install requirements | |
| run: conda install --quiet --file requirements-full.txt python==$PYTHON | |
| - name: List installed packages | |
| run: conda list | |
| - name: Build source and wheel distributions | |
| run: | | |
| make build | |
| echo "" | |
| echo "Generated files:" | |
| ls -lh dist/ | |
| - name: Install the package | |
| run: pip install --no-deps dist/*.whl | |
| - name: Cache the Ensaio datasets | |
| uses: actions/cache@v4 | |
| with: | |
| path: ${{ runner.temp }}/cache/ensaio | |
| # Use a constant key to reuse the datasets across all jobs | |
| key: ensaio | |
| - name: Build the documentation | |
| run: make -C doc clean all | |
| env: | |
| # Fetch the data from the GitHub releases to avoid overloading Zenodo | |
| ENSAIO_DATA_FROM_GITHUB: true | |
| # Define directory where sample data will be stored | |
| ENSAIO_DATA_DIR: ${{ runner.temp }}/cache/ensaio/ | |
| # Store the docs as a build artifact so we can deploy it later | |
| - name: Upload HTML documentation as an artifact | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs-${{ github.sha }} | |
| path: doc/_build/html | |
| ############################################################################# | |
| # Publish the documentation to gh-pages | |
| publish: | |
| runs-on: ubuntu-latest | |
| needs: build | |
| if: github.event_name == 'release' || github.event_name == 'push' | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4.1.6 | |
| # Fetch the built docs from the "build" job | |
| - name: Download HTML documentation artifact | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: docs-${{ github.sha }} | |
| path: doc/_build/html | |
| - name: Checkout the gh-pages branch in a separate folder | |
| uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 | |
| with: | |
| ref: gh-pages | |
| # Checkout to this folder instead of the current one | |
| path: deploy | |
| # Download the entire history | |
| fetch-depth: 0 | |
| - name: Push the built HTML to gh-pages | |
| run: | | |
| # Detect if this is a release or from the main branch | |
| if [[ "${{ github.event_name }}" == "release" ]]; then | |
| # Get the tag name without the "refs/tags/" part | |
| version="${GITHUB_REF#refs/*/}" | |
| else | |
| version=dev | |
| fi | |
| echo "Deploying version: $version" | |
| # Make the new commit message. Needs to happen before cd into deploy | |
| # to get the right commit hash. | |
| message="Deploy $version from $(git rev-parse --short HEAD)" | |
| cd deploy | |
| # Need to have this file so that Github doesn't try to run Jekyll | |
| touch .nojekyll | |
| # Delete all the files and replace with our new set | |
| echo -e "\nRemoving old files from previous builds of ${version}:" | |
| rm -rvf ${version} | |
| echo -e "\nCopying HTML files to ${version}:" | |
| cp -Rvf ../doc/_build/html/ ${version}/ | |
| # If this is a new release, update the link from /latest to it | |
| if [[ "${version}" != "dev" ]]; then | |
| echo -e "\nSetup link from ${version} to 'latest'." | |
| rm -f latest | |
| ln -sf ${version} latest | |
| fi | |
| # Stage the commit | |
| git add -A . | |
| echo -e "\nChanges to be applied:" | |
| git status | |
| # Configure git to be the GitHub Actions account | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git config user.name "github-actions[bot]" | |
| # If this is a dev build and the last commit was from a dev build | |
| # (detect if "dev" was in the previous commit message), reuse the | |
| # same commit | |
| if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then | |
| echo -e "\nAmending last commit:" | |
| git commit --amend --reset-author -m "$message" | |
| else | |
| echo -e "\nMaking a new commit:" | |
| git commit -m "$message" | |
| fi | |
| # Make the push quiet just in case there is anything that could leak | |
| # sensitive information. | |
| echo -e "\nPushing changes to gh-pages." | |
| git push -fq origin gh-pages 2>&1 >/dev/null | |
| echo -e "\nFinished uploading generated files." |