action.yml

# https://help.github.com/en/articles/metadata-syntax-for-github-actions
name: 'Sphinx to GitHub Pages'
description: 'GitHub Action to deploy Sphinx documentation to GitHub Pages'
author: 'Shengyu Zhang'
branding:
  color: 'green'
  icon: 'upload-cloud'
inputs:
  documentation_path:
    description: 'Path to Sphinx source files'
    required: false
    default: './docs'
  requirements_path:
    description: 'Path to requirements file, used in `pip install -r XXX` command'
    required: false
    default: './docs/requirements.txt'
  pyproject_extras:
    description: 'Extras of Requirement Specifier, used in `pip install .[XXX]` command'
    required: false
    default: 'docs'
  python_version:
    description: 'Version of Python'
    required: false
    default: '3.10'
  sphinx_version:
    description: 'Version of Sphinx'
    required: false
    default: ''
  cache:
    description: 'Enable cache to speed up documentation building'
    required: false
    default: false
  sphinx_build_options:
    description: 'Additional options passed to sphinx-build'
    required: false
    default: ''
  checkout:
    description: 'Whether to automatically checkout the repository, if false, user need to do it byself'
    required: false
    default: true
  publish:
    description: 'Whether to automatically publish the pages, if false, user need to manually publish by self'
    required: false
    default: true
outputs:
  page_url:
    description: 'URL to deployed GitHub Pages, only available when option publish is set to true'
    value: ${{ steps.deployment.outputs.page_url }}
  artifact:
    description: 'Directory where artifact (HTML documentation) is stored, user can use it to deploy GitHub Pages manually'
    value: ${{ steps.build.outputs.artifact }}

runs:
  using: "composite"
  steps:
    - name: Checkout
      uses: actions/checkout@v4
      if: ${{ inputs.checkout == 'true' && inputs.cache == 'true' }}
      with:
        fetch-depth: 0 # Required by git-restore-mtime
    - name: Checkout
      uses: actions/checkout@v4
      if: ${{ inputs.checkout == 'true' && inputs.cache == 'false' }}

    - name: Setup python
      uses: actions/setup-python@v5
      if: ${{ inputs.cache == 'true' }}
      with:
        python-version: ${{ inputs.python_version }}
        cache: 'pip'
    - name: Setup python
      uses: actions/setup-python@v5
      if: ${{ inputs.cache == 'false' }}
      with:
        python-version: ${{ inputs.python_version }}

    - name: Restore cache
      uses: actions/cache@v4
      if: ${{ inputs.cache == 'true' }}
      with:
        path: /tmp/sphinxnotes-pages
        # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#update-a-cache
        key: sphinxnotes-pages-${{ runner.os }}-${{ github.run_id }}
        restore-keys: |
          sphinxnotes-pages-${{ runner.os }}

    - name: Enable github problem matcher
      uses: sphinx-doc/github-problem-matcher@master

    - id: build
      name: Build documentation
      run: ${{ github.action_path }}/main.sh
      shell: bash
      env:
        # See https://github.com/actions/runner/issues/665
        INPUT_DOCUMENTATION_PATH: ${{ inputs.documentation_path }}
        INPUT_REQUIREMENTS_PATH: ${{ inputs.requirements_path }}
        INPUT_PYPROJECT_EXTRAS: ${{ inputs.pyproject_extras }}
        INPUT_SPHINX_VERSION: ${{ inputs.sphinx_version }}
        INPUT_CACHE: ${{ inputs.cache }}
        INPUT_SPHINX_BUILD_OPTIONS: ${{ inputs.sphinx_build_options }}

    - name: Setup Pages
      uses: actions/configure-pages@v4
      if: ${{ inputs.publish == 'true' }}

    - name: Fix file permissions
      shell: sh
      if: runner.os == 'Linux'
      # https://github.com/actions/deploy-pages/issues/188 
      run: |
        chmod -c -R +rX "$INPUT_PATH" |
        while read line; do
           echo "::warning title=Invalid file permissions automatically fixed::$line"
        done
      env:
        INPUT_PATH: ${{ steps.build.outputs.artifact }}

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      if: ${{ inputs.publish == 'true' }}
      with:
        path: ${{ steps.build.outputs.artifact }}
      
    - id: deployment
      name: Deploy to GitHub Pages
      uses: actions/deploy-pages@v4
      if: ${{ inputs.publish == 'true' }}