From 05fd42826fd4761991a493bc2ff8f65bf987f1da Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Thu, 9 Jan 2025 23:37:46 +0800 Subject: [PATCH 1/6] CI: Separate jobs to build and deploy documentation --- .github/workflows/ci_docs.yml | 56 +++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 08d608dd260..c504985a3a3 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -1,4 +1,4 @@ -# Build and deploy documentation +# Build and deploy documentation. # # This workflow builds the documentation on Linux/macOS/Windows. # @@ -42,11 +42,10 @@ concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} -permissions: - contents: write +permissions: {} jobs: - docs: + build-docs: name: ${{ matrix.os }} runs-on: ${{ matrix.os }} if: github.repository == 'GenericMappingTools/pygmt' @@ -168,6 +167,30 @@ jobs: GH_TOKEN: ${{ github.token }} REF_NAME: ${{ github.ref_name }} + - name: Upload HMTL documentation artifact + uses: actions/upload-artifact@v4.5.0 + with: + name: pygmt-docs-html + path: doc/_build/html/ + if: matrix.os == 'ubuntu-latest' + + deploy-docs: + name: Deploy documentation + needs: build-docs + runs-on: ubuntu-latest + if: (github.event_name == 'release' || github.event_name == 'push') && github.repository == 'GenericMappingTools/pygmt' + permissions: + contents: write + + steps: + # Checkout current git repository + - name: Checkout + uses: actions/checkout@v4.2.2 + with: + # fetch all history so that setuptools-scm works + fetch-depth: 0 + persist-credentials: false + - name: Checkout the gh-pages branch uses: actions/checkout@v4.2.2 with: @@ -177,7 +200,12 @@ jobs: # Download the entire history fetch-depth: 0 persist-credentials: true - if: (github.event_name == 'release' || github.event_name == 'push') && (matrix.os == 'ubuntu-latest') + + - name: Download HTML documentation artifact + uses: actions/download-artifact@v4.1.8 + with: + name: pygmt-docs-html + path: pygmt-docs-html - name: Push the built HTML to gh-pages run: | @@ -189,10 +217,10 @@ jobs: 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. + # 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 + cd deploy/ # Create some files in the root directory. # .nojekyll: Need to have this file so that GitHub doesn't try to run Jekyll touch .nojekyll @@ -204,7 +232,7 @@ jobs: 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}/ + cp -Rvf ../pygmt-docs-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'." @@ -218,9 +246,8 @@ jobs: # 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 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" @@ -228,9 +255,8 @@ jobs: 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. + # 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') From 45260ccdc071e31116db47e21e6c7a995c306ac7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 9 Apr 2025 18:51:09 +0800 Subject: [PATCH 2/6] Add the build_docs composite action to simplify the main workflow --- .../workflows/actions/build_docs/action.yml | 75 +++++++++++++++++++ .github/workflows/ci_docs.yml | 65 +--------------- 2 files changed, 77 insertions(+), 63 deletions(-) create mode 100644 .github/workflows/actions/build_docs/action.yml diff --git a/.github/workflows/actions/build_docs/action.yml b/.github/workflows/actions/build_docs/action.yml new file mode 100644 index 00000000000..adfaae867a5 --- /dev/null +++ b/.github/workflows/actions/build_docs/action.yml @@ -0,0 +1,75 @@ +name: Build Docs +description: Build the documentation +inputs: + os: + description: 'Operating system' + required: true + default: 'ubuntu-latest' + +runs: + using: 'composite' + steps: + - 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/setup-micromamba@v2.0.4 + with: + environment-name: pygmt + cache-environment: true + # environment cache is persistent for one week. + cache-environment-key: micromamba-environment-${{ steps.date.outputs.date }} + create-args: >- + python=3.13 + gmt=6.5.0 + ghostscript=10.04.0 + numpy + pandas + xarray + netCDF4 + packaging + contextily + geopandas + ipython + pyarrow-core + rioxarray + make + pip + python-build + geodatasets + myst-nb + panel + sphinx>=6.2 + sphinx-autodoc-typehints + sphinx-copybutton + sphinx-design + sphinx-gallery + sphinx_rtd_theme + cairosvg + sphinxcontrib-svg2pdfconverter + tectonic + + # 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/* + + - name: Build the HTML documentation + run: make -C doc clean html + + - name: Build the PDF documentation + run: make -C doc pdf diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index c504985a3a3..264f48fbe66 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -76,70 +76,9 @@ jobs: fetch-depth: 0 persist-credentials: false - - 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/setup-micromamba@v2.0.4 + - uses: ./.github/workflows/actions/build_docs with: - environment-name: pygmt - cache-environment: true - # environment cache is persistent for one week. - cache-environment-key: micromamba-environment-${{ steps.date.outputs.date }} - create-args: >- - python=3.13 - gmt=6.5.0 - ghostscript=10.04.0 - numpy - pandas - xarray - netCDF4 - packaging - contextily - geopandas - ipython - pyarrow-core - rioxarray - make - pip - python-build - geodatasets - myst-nb - panel - sphinx>=6.2 - sphinx-autodoc-typehints - sphinx-copybutton - sphinx-design - sphinx-gallery - sphinx_rtd_theme - cairosvg - sphinxcontrib-svg2pdfconverter - tectonic - - # 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/* - - - name: Build the HTML documentation - run: make -C doc clean html - - - name: Build the PDF documentation - run: make -C doc pdf + os: ${{ matrix.os }} - name: Create the HTML ZIP archive and rename the PDF file run: | From 4ed63aa816e5984dcd0bec381232748b7e222c55 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Wed, 9 Apr 2025 19:08:22 +0800 Subject: [PATCH 3/6] Add default shell --- .github/workflows/actions/build_docs/action.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/actions/build_docs/action.yml b/.github/workflows/actions/build_docs/action.yml index adfaae867a5..a951be6a1ce 100644 --- a/.github/workflows/actions/build_docs/action.yml +++ b/.github/workflows/actions/build_docs/action.yml @@ -8,10 +8,12 @@ inputs: runs: using: 'composite' + steps: - name: Get current week number of year id: date run: echo "date=$(date +%Y-W%W)" >> $GITHUB_OUTPUT # e.g., 2024-W19 + shell: bash # Install Micromamba with conda-forge dependencies - name: Setup Micromamba @@ -59,6 +61,7 @@ runs: # 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 + shell: bash -l {0} env: GH_TOKEN: ${{ github.token }} @@ -67,9 +70,12 @@ runs: run: | python -m build --sdist python -m pip install dist/* + shell: bash - name: Build the HTML documentation run: make -C doc clean html + shell: bash -l {0} - name: Build the PDF documentation run: make -C doc pdf + shell: bash -l {0} From 4ac87d940a79fa6c35b0f21f5abd25710a5d20b1 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 10 May 2025 15:07:43 +0800 Subject: [PATCH 4/6] Use correct shell --- .github/workflows/actions/build_docs/action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/actions/build_docs/action.yml b/.github/workflows/actions/build_docs/action.yml index a951be6a1ce..0c0dc51e248 100644 --- a/.github/workflows/actions/build_docs/action.yml +++ b/.github/workflows/actions/build_docs/action.yml @@ -70,7 +70,7 @@ runs: run: | python -m build --sdist python -m pip install dist/* - shell: bash + shell: bash -l {0} - name: Build the HTML documentation run: make -C doc clean html From 693694ebc72d34ef5e11a6aaa2d3175468eeb785 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 10 May 2025 15:17:50 +0800 Subject: [PATCH 5/6] Add more comment to the build_docs action --- .github/workflows/actions/build_docs/action.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/actions/build_docs/action.yml b/.github/workflows/actions/build_docs/action.yml index 0c0dc51e248..1c42fa87b05 100644 --- a/.github/workflows/actions/build_docs/action.yml +++ b/.github/workflows/actions/build_docs/action.yml @@ -1,3 +1,12 @@ +# +# A composite action to build the documentation. +# +# To call the action, use: +# ``` +# - uses: ./.github/workflows/actions/build_docs +# os: ubuntu-latest +# ``` +# name: Build Docs description: Build the documentation inputs: From 0b1fb0100623c6ce915c618058ce493986be934e Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 10 May 2025 16:40:29 +0800 Subject: [PATCH 6/6] Fix artifact name --- .github/workflows/ci_docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index 264f48fbe66..487cad3646d 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -92,7 +92,7 @@ jobs: uses: actions/upload-artifact@v4.6.2 if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest' with: - name: artifact-pygmt-docs-pdf + name: pygmt-docs-pdf path: doc/_build/pygmt-docs.pdf - name: Copy the HTML ZIP archive and PDF to the html folder for dev version