docs.yml

name: NEURON Documentation

concurrency:
  # Don't cancel on master, creating a PR when a push workflow is already going will cancel the push workflow in favour of the PR workflow
  group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/master' && github.run_id || github.event.number && github.head_ref || github.ref_name }}
  cancel-in-progress: true

on:
  merge_group:
  push:
    branches:
      - master
      - release/**
  pull_request:
    branches:
      - master
      - release/**

env:
  DEFAULT_PY_VERSION: '3.11'

jobs:
  documentation:
    runs-on: ubuntu-20.04

    name: Documentation

    timeout-minutes: 25

    steps:

      - name: Install apt packages
        run: |
          sudo apt-get update --fix-missing
          sudo apt-get install build-essential libopenmpi-dev libmpich-dev libx11-dev libxcomposite-dev mpich openmpi-bin
          sudo apt-get install ffmpeg doxygen pandoc
        shell: bash

      - name: Set up Python@${{ env.DEFAULT_PY_VERSION }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.DEFAULT_PY_VERSION }}

      - uses: actions/checkout@v4

      - name: Install Python dependencies
        working-directory: ${{runner.workspace}}/nrn
        run: |
          python -m pip install --upgrade pip -r nrn_requirements.txt

      - name: Install Python documentation dependencies
        working-directory: ${{runner.workspace}}/nrn
        run: |
          python -m pip install --upgrade -r docs/docs_requirements.txt

      - name: Documentation
        id: documentation
        shell: bash
        working-directory: ${{runner.workspace}}/nrn
        run:  |
          echo "-------- NEURON wheel --------";
          python setup.py build_ext bdist_wheel;
          neuron_wheel=dist/NEURON*.whl;
          echo "-------- install wheel --------"
          python -m pip install $neuron_wheel;
          echo "-------- now build docs--------";
          python setup.py docs;
          echo "-------- disable jekyll--------";
          pushd docs/_build;
          touch .nojekyll;
          echo "-------- OK to deploy! --------";
          echo "OK_TO_DEPLOY_DOCS=true" >> $GITHUB_ENV

      # This step will set up an SSH connection on tmate.io for live debugging.
      # To enable it, you have to:
      #   * add 'live-debug-docs' to your PR title
      #   * push something to your PR branch (note that just re-running the pipeline disregards the title update)
      - name: live debug session on failure (manual steps required, check `.github/docs.yml`)
        if: failure() && contains(github.event.pull_request.title, 'live-debug-docs')
        uses: mxschmitt/action-tmate@v3

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        if: env.OK_TO_DEPLOY_DOCS == 'true' && github.ref == 'refs/heads/master'
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: ${{runner.workspace}}/nrn/docs/_build # The folder the action should deploy.
          single-commit: true #have a single commit on the deployment branch instead of maintaining the full history