DOC: Add basic tutorial "Plotting polygons" #12426
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 and deploy documentation | |
| # | |
| # This workflow builds the documentation on Linux/macOS/Windows. | |
| # | |
| # It is run on every commit to the main and pull request branches, and also | |
| # when a new release is published. | |
| # In draft pull requests, only the job on Linux is triggered to save on | |
| # Continuous Integration resources. | |
| # | |
| # On the main branch, the workflow also handles the documentation deployment: | |
| # | |
| # * Updating the development documentation by pushing the built HTML pages | |
| # from the main branch onto the dev folder of the gh-pages branch. | |
| # * Updating the latest documentation link to the new release. | |
| # | |
| name: Docs | |
| on: | |
| push: | |
| branches: [ main ] | |
| paths: | |
| - 'pygmt/**/*.py' | |
| - '!pygmt/tests/**' | |
| - 'doc/**' | |
| - 'examples/**' | |
| - 'README.md' | |
| - '.github/workflows/ci_docs.yml' | |
| pull_request: | |
| types: [opened, reopened, synchronize, ready_for_review] | |
| paths: | |
| - 'pygmt/**/*.py' | |
| - '!pygmt/tests/**' | |
| - 'doc/**' | |
| - 'examples/**' | |
| - 'README.md' | |
| - '.github/workflows/ci_docs.yml' | |
| workflow_dispatch: | |
| release: | |
| types: | |
| - published | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} | |
| jobs: | |
| docs: | |
| name: ${{ matrix.os }} | |
| runs-on: ${{ matrix.os }} | |
| if: github.repository == 'GenericMappingTools/pygmt' | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| os: [ubuntu-latest, macos-latest, windows-latest] | |
| # Is it a draft Pull Request (true or false)? | |
| isDraft: | |
| - ${{ github.event.pull_request.draft }} | |
| # Only run one job (Ubuntu + Python 3.12) for draft PRs | |
| exclude: | |
| - os: macos-latest | |
| isDraft: true | |
| - os: windows-latest | |
| isDraft: true | |
| timeout-minutes: 30 | |
| defaults: | |
| run: | |
| shell: bash -l {0} | |
| steps: | |
| # Checkout current git repository | |
| - name: Checkout | |
| uses: actions/[email protected] | |
| with: | |
| # fetch all history so that setuptools-scm works | |
| fetch-depth: 0 | |
| - name: Get current week number of year | |
| id: date | |
| run: echo "date=$(date +%Y-W%W)" >> $GITHUB_OUTPUT # e.g., 2024-W19 | |
| # Install Micromamba with conda-forge dependencies | |
| - name: Setup Micromamba | |
| uses: mamba-org/[email protected] | |
| with: | |
| environment-name: pygmt | |
| condarc: | | |
| channels: | |
| - conda-forge | |
| - nodefaults | |
| cache-downloads: false | |
| cache-environment: true | |
| # environment cache is persistent for one week. | |
| cache-environment-key: micromamba-environment-${{ steps.date.outputs.date }} | |
| create-args: >- | |
| python=3.12 | |
| gmt=6.5.0 | |
| ghostscript=10.04.0 | |
| numpy | |
| pandas | |
| xarray | |
| netCDF4 | |
| packaging | |
| contextily | |
| geopandas<1.0 | |
| ipython | |
| pyarrow | |
| rioxarray | |
| make | |
| pip | |
| python-build | |
| myst-nb | |
| panel | |
| sphinx | |
| sphinx-autodoc-typehints | |
| sphinx-copybutton | |
| sphinx-design | |
| sphinx-gallery | |
| sphinx_rtd_theme<3.0 | |
| # Download cached remote files (artifacts) from GitHub | |
| - name: Download remote data from GitHub | |
| run: | | |
| # Download cached files to ~/.gmt directory and list them | |
| gh run download --name gmt-cache --dir ~/.gmt/ | |
| # Change modification times of the two files, so GMT won't refresh it | |
| touch ~/.gmt/gmt_data_server.txt ~/.gmt/gmt_hash_server.txt | |
| ls -lhR ~/.gmt | |
| env: | |
| GH_TOKEN: ${{ github.token }} | |
| # Install the package that we want to test | |
| - name: Install the package | |
| run: | | |
| python -m build --sdist | |
| python -m pip install dist/* | |
| # Build the documentation | |
| - name: Build the documentation | |
| run: make -C doc clean all | |
| - name: Checkout the gh-pages branch | |
| uses: actions/[email protected] | |
| with: | |
| ref: gh-pages | |
| # Checkout to this folder instead of the current one | |
| path: deploy | |
| # Download the entire history | |
| fetch-depth: 0 | |
| if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest') | |
| - 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." | |
| if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest') |