docs.yml

# name: Build Docs

# # We don't want pushes (or PRs) to gh-pages to kick anything off
# on:
#   push:
#     branches:
#       - main
#       - '[0-9]+.[0-9]+.x'
#     tags:
#       - v[0-9]+.[0-9]+.[0-9]+
#   pull_request:

# concurrency:
#   group: ${{ github.workflow}}-${{ github.head_ref }}
#   cancel-in-progress: true

# jobs:
#   #
#   # Build our docs on Linux against multiple Pythons
#   #
#   Docs:
#     name: "Linux ${{ matrix.python-version }}"
#     runs-on: ubuntu-latest
#     strategy:
#       fail-fast: false
#       matrix:
#         python-version: [3.11, 3.12, 3.13]
#         check-links: [false]
#         include:
#           - python-version: 3.14
#             check-links: true
#     outputs:
#       doc-version: ${{ steps.build-docs.outputs.doc-version }}

#     steps:
#     - name: Checkout source
#       uses: actions/checkout@v6
#       with:
#         fetch-depth: 150
#         persist-credentials: false

#     # Can't use fetch-tags on a tag apparently. See actions/checkout#1467.
#     - name: Get tags
#       run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*

#     - name: Install using PyPI
#       uses: ./.github/actions/install-pypi
#       with:
#         type: 'doc'
#         python-version: ${{ matrix.python-version }}
#         need-extras: true
#         need-cartopy: true

#     - name: Build docs
#       id: build-docs
#       uses: ./.github/actions/build-docs
#       with:
#         run-linkchecker: ${{ github.event_name == 'pull_request' && matrix.check-links == true }}
#         key: ${{ runner.os }}-${{ matrix.python-version }}

#   Deploy:
#     if: ${{ github.event_name != 'pull_request' }}
#     needs: Docs
#     environment:
#       name: github-pages
#     runs-on: ubuntu-slim
#     env:
#       DOC_VERSION: dev
#     permissions:
#       contents: write

#     steps:
#     - name: Download doc build
#       uses: actions/download-artifact@v7
#       with:
#         name: Linux-3.13-docs
#         path: ./docs/build/html

#     # This overrides the version "dev" with the proper version if we're building off a
#     # branch that's not main (which is confined to n.nn.x above) or on a tag.
#     - name: Set doc version
#       if: ${{ github.event_name != 'push' || !contains(github.ref, 'main') }}
#       run: echo "DOC_VERSION=v${{ needs.Docs.outputs.doc-version }}" >> $GITHUB_ENV

#     - name: Export doc version
#       run: echo "doc-version=${{ env.DOC_VERSION }}" >> $GITHUB_OUTPUT

#     - name: Upload to GitHub Pages
#       uses: peaceiris/actions-gh-pages@v4
#       with:
#         github_token: ${{ secrets.GITHUB_TOKEN }}
#         publish_dir: ./docs/build/html
#         exclude_assets: '.buildinfo,_static/jquery-*.js,_static/underscore-*.js'
#         destination_dir: ./${{ env.DOC_VERSION }}
#         keep_files: false
#         full_commit_message: Deploy ${{ env.DOC_VERSION }} to GitHub Pages

#   UpdateVersions:
#     needs: Deploy
#     if: ${{ needs.Deploy.outputs.doc-version != 'dev' }}
#     name: "Manage doc versions"
#     environment:
#       name: github-pages
#     runs-on: ubuntu-slim
#     permissions:
#       contents: write

#     steps:
#     - name: Checkout docs
#       uses: actions/checkout@v6
#       with:
#         ref: "gh-pages"

#     - name: Set up Python
#       uses: actions/setup-python@v6

#     - name: Install packaging
#       run: python -m pip install packaging

#     - name: Update listing of versions
#       run: |
#         python << EOF
#         import json
#         from pathlib import Path
#         from packaging import version

#         # Get all paths that are versions
#         vers = sorted(version.parse(str(p)) for p in Path().glob('v[0-9]*'))

#         # Set up our version dictionary
#         versions = dict(versions=['latest', 'dev'],
#                         latest=f'v{vers[-1].major}.{vers[-1].minor}', prereleases=[])
#         versions['versions'].extend(f'v{v.major}.{v.minor}' for v in vers[-4:])

#         # Write to JSON file
#         with open('versions.json', 'wt') as verfile:
#             json.dump(versions, verfile)

#         # Update the 'latest' symlink
#         latest = Path('latest')
#         latest.unlink(missing_ok=True)
#         latest.symlink_to(versions['latest'], target_is_directory=True)
#         EOF

#     - name: Commit changes
#       run: |
#         git config user.name $GITHUB_ACTOR
#         git config user.email $GITHUB_ACTOR@users.noreply.github.com
#         git add latest versions.json
#         git commit -am "Update version listing and latest link" || true
#         git push