documentation.yml

name: Documentation

# Run on all pushes and pull requests, and on demand
on:
  push:
  pull_request:
  workflow_dispatch:

# Limit workflow permissions
permissions:
  contents: read

# Limit simultaneous workflow runs
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

env:
  FORCE_COLOR: "1"

jobs:
  render:
    name: Render
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python 3.10
      uses: actions/setup-python@v4
      with:
        python-version: "3.10"  # Interpolation.py doesn't support Python 3.11 [2023-07]
        cache: 'pip'
        cache-dependency-path: |
          requirements/base.txt
          requirements/doc.txt

    - name: Install Pandoc
      run: sudo apt-get install --yes pandoc

    - name: Update pip
      run: python -m pip install --upgrade pip

    - name: Install HARK
      run: python -m pip install .[doc]

    - name: Run Sphinx
      run: >
        sphinx-build
        -M html Documentation HARK-docs
        -T
        -W
        -j auto

    - name: Set up git for deployment
      run: |
        git config user.name "${{ github.actor }}"
        git config user.email "${{ github.actor }}@users.noreply.github.com"
        git config --local --unset-all http.https://github.com/.extraheader

    - name: Commit all rendered HTML files
      run: |
        git switch --orphan gh-pages
        git add --all HARK-docs/html
        git commit -qm "Documentation from @ ${{ github.repository }}@${{ github.sha }}"

    - name: Deploy to GitHub Pages
      # Only deploy to Pages on pushes to HEAD
      if: (github.repository_owner == 'Econ-ARK') && (github.event_name == 'push') && (github.ref_name == 'master')
      run: >
        git push
        --force 
        https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}
        `git subtree split --prefix HARK-docs/html gh-pages`:refs/heads/gh-pages

  lint:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: 3
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        python -m pip install --upgrade sphinx-lint
    - name: Lint documentation with sphinx-lint
      run: >
        sphinx-lint
        --ignore Documentation/example_notebooks/GenIncProcessModel.py
        --enable all
        --max-line-length 85 
        README.md
        Documentation/