build-docs.yml

---
# 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/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: ${{ 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 "actions@github.com"
                git config --global user.name "GitHub actions"

                git clone git@github.com: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;