DocumentationBuilder #504
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 | |
| MIN_PYTHON_VERSION: '3.9' | |
| HEAD_COMMIT_MESSAGE: ${{ github.event.head_commit.message }} | |
| 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/[email protected] | |
| 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: ${{ env.MIN_PYTHON_VERSION }} | |
| - 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 | |
| # 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 }} | |
| # 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 & | |
| - name: Setup python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ env.MIN_PYTHON_VERSION }} | |
| - name: Install tox | |
| run: python -m pip install tox | |
| - name: Show tox config | |
| run: tox c | |
| # Run the doc build | |
| # We let tox handle creating virtual env and install dependencies. | |
| # 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: | | |
| set -o pipefail; | |
| export PATTERN=$(cat pattern.txt) | |
| tox run \ | |
| --colored yes \ | |
| --list-dependencies \ | |
| -e doc -- $(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 | |
| deploy_on_main: | |
| runs-on: ubuntu-latest | |
| needs: [build_docs] | |
| if: ${{ contains(fromJSON('["push", "workflow_dispatch", "schedule"]'), github.event_name)}} | |
| steps: | |
| - name: Add SSH key | |
| env: | |
| SSH_AUTH_SOCK: /tmp/ssh_agent.sock | |
| run: | | |
| mkdir -p ~/.ssh | |
| ssh-keyscan github.com >> ~/.ssh/known_hosts | |
| echo "${{ secrets.ACTIONS_SSH_DEPLOY }}" > ~/.ssh/github_actions | |
| chmod 600 ~/.ssh/github_actions | |
| ssh-agent -a $SSH_AUTH_SOCK > /dev/null | |
| ssh-add ~/.ssh/github_actions | |
| - uses: actions/download-artifact@v4 | |
| with: | |
| name: doc | |
| path: ~/doc/_build/html | |
| - name: deploy | |
| env: | |
| SSH_AUTH_SOCK: /tmp/ssh_agent.sock | |
| run: | | |
| git config --global user.email "[email protected]" | |
| git config --global user.name "GitHub actions" | |
| git clone [email protected]:nilearn/nilearn.github.io.git ~/nilearn.github.io --depth=1 | |
| cd ~/nilearn.github.io; | |
| git checkout main | |
| git remote -v | |
| git fetch origin | |
| git reset --hard origin/main | |
| git clean -xdf | |
| echo "Deploying dev docs."; | |
| rm -Rf dev; | |
| cp -a ~/doc/_build/html dev; | |
| git add -A; | |
| git commit -m "Dev docs https://github.com/nilearn/nilearn/commit/${{ github.event.head_commit.id }} : $HEAD_COMMIT_MESSAGE"; | |
| git push origin main; |