DocumentationBuilder #4279
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
| --- | |
| # Workflow to build the documentation. | |
| # | |
| # On pull requests, partial builds are run except | |
| # if "[full doc]" is defined in commit message. | |
| # Full builds are always run on "main". | |
| # This is done every time there is a push on "main" and every week. | |
| # | |
| # Data is cached after the get_data job to be passed to the build_docs job. | |
| # Data can be cached and restore across attempts of a run of this workflow. | |
| # Data can be cached and restored across run of this workflow. | |
| # Using "[force download]" in the commit message should prevent from using any cache. | |
| name: DocumentationBuilder | |
| on: | |
| push: | |
| branches: | |
| - main | |
| pull_request: | |
| branches: | |
| - '*' | |
| schedule: | |
| # Run every Monday at 8am UTC | |
| - cron: 0 8 * * 1 | |
| # Allows you to run this workflow manually from the Actions tab | |
| workflow_dispatch: | |
| concurrency: | |
| group: ${{ github.workflow }}-${{ github.ref }} | |
| cancel-in-progress: true | |
| env: | |
| # Force to use color | |
| FORCE_COLOR: true | |
| BROWSER: /usr/bin/firefox | |
| DISPLAY: :99.0 | |
| NILEARN_DATA: /home/runner/work/nilearn/nilearn/nilearn_data | |
| jobs: | |
| # Make citation metadata from CITATION.cff is valid. | |
| # as it is used in the documentation build. | |
| validate_cff: | |
| # This prevents this workflow from running on a fork. | |
| # To test this workflow on a fork, uncomment the following line. | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout nilearn | |
| uses: actions/checkout@v4 | |
| - name: Check whether the citation metadata from CITATION.cff is valid | |
| uses: citation-file-format/cffconvert-github-action@2.0.0 | |
| with: | |
| args: --validate | |
| get_data: | |
| # This prevents this workflow from running on a fork. | |
| # To test this workflow on a fork, uncomment the following line. | |
| if: github.repository == 'nilearn/nilearn' | |
| runs-on: ubuntu-latest | |
| defaults: | |
| run: | |
| shell: bash -el {0} | |
| steps: | |
| - name: Checkout nilearn | |
| uses: actions/checkout@v4 | |
| with: | |
| # If pull request, checkout HEAD commit with all commit history | |
| ref: ${{ github.event.pull_request.head.sha }} | |
| fetch-depth: 0 | |
| - name: Merge with upstream | |
| run: ./build_tools/github/merge_upstream.sh | |
| # Set up environment | |
| - name: Setup python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| - name: Install packages | |
| run: | | |
| python -m pip install --user --upgrade pip setuptools | |
| python -m pip install . | |
| - name: Check if we are doing a full or partial build | |
| run: ./build_tools/github/build_type.sh | |
| env: | |
| COMMIT_SHA: ${{ github.event.pull_request.head.sha }} | |
| - name: Verify build type | |
| id: build-type | |
| run: | | |
| echo "PATTERN = $(cat pattern.txt)" | |
| echo "BUILD = $(cat build.txt)" | |
| echo "build=$(cat build.txt)" >> $GITHUB_OUTPUT | |
| - name: Determine if we will use cached data | |
| run: ./build_tools/github/determine_restore_data.sh | |
| - name: Get cache key | |
| id: cache-key | |
| run: | | |
| if [[ $(cat restore.txt) == "true" ]]; then | |
| echo "restore=true" >> $GITHUB_OUTPUT | |
| fi | |
| - name: Key for cache based on month number | |
| run: date +%m > month_num; | |
| - name: Get cache from a previous attempts on this PR or branch | |
| if: steps.cache-key.outputs.restore == 'true' | |
| id: restore-previous-run | |
| uses: actions/cache/restore@v4 | |
| with: | |
| path: nilearn_data | |
| key: data_cache-${{ github.workflow }}_ref-${{ github.ref }}_run-${{ github.run_number }}_attempt-${{ github.run_attempt }} | |
| restore-keys: | | |
| data_cache-${{ github.workflow }}_ref-${{ github.ref }}_run-${{ github.run_number }} | |
| data_cache-${{ github.workflow }}_ref-${{ github.ref }} | |
| - name: Get data from a previous successful run for full builds | |
| # only run it if we did not get the data from a previous attempt | |
| if: ${{ steps.build-type.outputs.build == 'html-strict' && steps.cache-key.outputs.restore == 'true' && steps.restore-previous-run.outputs.cache-hit | |
| != 'true' }} | |
| id: restore-previous-full-build | |
| uses: actions/cache@v4 | |
| with: | |
| path: nilearn_data | |
| key: data_cache-${{ github.workflow }}_month-${{ hashFiles('month_num') }} | |
| - name: Get data for reports from a previous successful run | |
| # only run it if we did not get the data from a previous attempt | |
| if: ${{ steps.cache-key.outputs.restore == 'true' && steps.restore-previous-run.outputs.cache-hit != 'true' && steps.restore-previous-full-build.outputs.cache-hit | |
| != 'true' }} | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| nilearn_data/adhd | |
| nilearn_data/development_fmri | |
| nilearn_data/difumo_atlases | |
| nilearn_data/ds000030 | |
| nilearn_data/fiac_nilearn.glm | |
| nilearn_data/icbm152_2009 | |
| nilearn_data/miyawaki2008 | |
| nilearn_data/msdl_atlas | |
| nilearn_data/oasis1 | |
| nilearn_data/schaefer_2018 | |
| nilearn_data/yeo_2011 | |
| key: data_cache-${{ github.workflow }}_month-${{ hashFiles('month_num') }} | |
| - name: Get data | |
| run: | | |
| echo "Download data required for building reports in doc" | |
| python doc/get_data_examples.py | |
| echo "Download data required for this doc build type" | |
| BUILD_TYPE=$(cat build.txt) | |
| python doc/get_data_examples.py $BUILD_TYPE | |
| - name: Save cache to pass to build_docs job | |
| uses: actions/cache/save@v4 | |
| if: always() | |
| with: | |
| path: nilearn_data | |
| key: data_cache-${{ github.workflow }}_ref-${{ github.ref }}_run-${{ github.run_number }}_attempt-${{ github.run_attempt }} | |
| # Steps to build the documentation. | |
| build_docs: | |
| needs: [get_data, validate_cff] | |
| # This prevents this workflow from running on a fork. | |
| # To test this workflow on a fork, uncomment the following line. | |
| runs-on: ubuntu-latest | |
| defaults: | |
| run: | |
| shell: bash -el {0} | |
| steps: | |
| - name: Checkout nilearn | |
| uses: actions/checkout@v4 | |
| with: | |
| # If pull request, checkout HEAD commit with all commit history | |
| ref: ${{ github.event.pull_request.head.sha }} | |
| fetch-depth: 0 | |
| - name: Merge with upstream | |
| run: ./build_tools/github/merge_upstream.sh | |
| # Set up environment | |
| - name: Install apt packages | |
| run: | | |
| sudo -E apt-get -yq update | |
| sudo -E apt-get -yq --no-install-suggests --no-install-recommends install \ | |
| dvipng texlive-latex-base texlive-latex-extra | |
| - name: Setup python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| # Install the local version of the library, along with both standard and testing-related dependencies | |
| # The `doc` dependency group is included because the build_docs job uses this script. | |
| # See pyproject.toml for dependency group options | |
| - name: Install packages | |
| run: | | |
| python -m pip install --user --upgrade pip setuptools | |
| python -m pip install .[plotting,doc] | |
| # Check if we are doing a full or partial build | |
| - name: Find build type | |
| run: ./build_tools/github/build_type.sh | |
| env: | |
| COMMIT_SHA: ${{ github.event.pull_request.head.sha }} | |
| - name: Verify build type | |
| run: | | |
| echo "PATTERN = $(cat pattern.txt)" | |
| echo "BUILD = $(cat build.txt)" | |
| - name: Key for cache based on month number | |
| run: date +%m > month_num; | |
| - name: Get data from the get_data job | |
| uses: actions/cache@v4 | |
| with: | |
| path: nilearn_data | |
| key: data_cache-${{ github.workflow }}_ref-${{ github.ref }}_run-${{ github.run_number }}_attempt-${{ github.run_attempt }} | |
| restore-keys: | | |
| data_cache-${{ github.workflow }}_ref-${{ github.ref }}_run-${{ github.run_number }} | |
| # Update the authors file and the names file | |
| # in case a contributor has been added to citation.cff | |
| # but did not run the maint_tools/citation_cff_maint.py script. | |
| - name: update AUTHORS.rst and doc/changes/names.rst | |
| run: python maint_tools/citation_cff_maint.py | |
| # Set up and launch a virtual browser needed for one example to run | |
| # without stalling the job. The example launches an html in the browser. | |
| - name: Set up display server for virtual browser | |
| run: Xvfb -ac :99 -screen 0 1280x1024x16 > /dev/null 2>&1 & | |
| # Run the doc build. | |
| # If no data is restored in previous steps, | |
| # the data will be downloaded during the build | |
| # (this only applies for full builds; | |
| # no data is downloaded for partial builds). | |
| - name: Build docs | |
| id: build-docs | |
| run: | | |
| cd doc; | |
| set -o pipefail; | |
| PATTERN=$(cat ../pattern.txt) make $(cat ../build.txt) 2>&1 | tee log.txt; | |
| - name: Check for unreplaced argument in docstrings | |
| if: always() | |
| run: | | |
| ./build_tools/github/fill_doc_check.sh | |
| cat doc/tmp/doc_check.txt | |
| - name: Upload documentation | |
| if: steps.build-docs.outcome == 'success' | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: doc | |
| path: doc/_build/html | |
| # Trigger hosting / deploy of the doc on nilearn.github.io via circle-ci | |
| # We get the url for the artifacts for circle-ci from https://nightly.link/ | |
| - name: Trigger hosting jobs on circle ci | |
| if: steps.build-docs.outcome == 'success' | |
| run: | | |
| GITHUB_RUN_URL="https://nightly.link/${{ github.repository }}/actions/runs/${{ github.run_id }}" | |
| curl --request POST \ | |
| --url https://circleci.com/api/v2/project/gh/${{ github.repository }}/pipeline \ | |
| --header "Circle-Token: ${{ secrets.CIRCLE_CI_TOKEN }}" \ | |
| --header "content-type: application/json" \ | |
| --header "x-attribution-actor-id: github_actions" \ | |
| --header "x-attribution-login: github_actions" \ | |
| --data \{\"branch\":\"${{ github.head_ref }}\",\"parameters\":\{\"GITHUB_RUN_URL\":\"$GITHUB_RUN_URL\"\}\} |