Sphinx gh-pages deploy with adapted recursive checkout trials

.github/workflows/build-docs.yml

@@ -14,7 +14,7 @@ jobs:
       id-token: write
     steps:
     - id: deployment
-      uses: sphinx-notes/pages@v3
+      uses: ./.github/workflows/sphinx-notes-mod.yml
       with:
         requirements_path: ./requirements.txt
         publish: true

.github/workflows/sphinx-notes-mod.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+
+# set -x
+set -e
+
+echo ::group:: Initialize various paths
+
+repo_dir=$GITHUB_WORKSPACE/$INPUT_REPOSITORY_PATH
+doc_dir=$repo_dir/$INPUT_DOCUMENTATION_PATH
+# https://stackoverflow.com/a/4774063/4799273
+action_dir=$GITHUB_ACTION_PATH
+
+echo Action: $action_dir
+echo Workspace: $GITHUB_WORKSPACE
+echo Repository: $repo_dir
+echo Documentation: $doc_dir
+
+echo ::endgroup::
+
+# The actions doesn't depends on any images,
+# so we have to try various package manager.
+echo ::group:: Installing Sphinx
+
+echo Installing sphinx via pip
+if [ -z "$INPUT_SPHINX_VERSION" ] ; then
+    pip3 install -U sphinx
+else
+    pip3 install -U sphinx==$INPUT_SPHINX_VERSION
+fi
+
+echo Adding ~/.local/bin to system path
+PATH=$HOME/.local/bin:$PATH
+if ! command -v sphinx-build &>/dev/null; then
+    echo Sphinx is not successfully installed
+    exit 1
+else
+    echo Everything goes well
+fi
+
+echo ::endgroup::
+
+if [ ! -z "$INPUT_REQUIREMENTS_PATH" ] ; then
+    echo ::group:: Installing dependencies declared by $INPUT_REQUIREMENTS_PATH
+    if [ -f "$INPUT_REQUIREMENTS_PATH" ]; then
+        pip3 install -r "$INPUT_REQUIREMENTS_PATH"
+    else
+        echo No $INPUT_REQUIREMENTS_PATH found, skipped
+    fi
+    echo ::endgroup::
+fi
+
+if [ ! -z "$INPUT_PYPROJECT_EXTRAS" ] ; then
+    echo ::group:: Installing dependencies declared by pyproject.toml[$INPUT_PYPROJECT_EXTRAS]
+    if [ -f "pyproject.toml" ]; then
+        pip3 install .[$INPUT_PYPROJECT_EXTRAS]
+    else
+        echo No pyproject.toml found, skipped
+    fi
+    echo ::endgroup::
+fi
+
+echo ::group:: Preparations for incremental build
+
+# Sphinx HTML builder will rebuild the whole project when modification time
+ # (mtime) of templates of theme newer than built result. [1]
+#
+# These theme templates vendored in pip packages are newly installed,
+# so their mtime always newr than the built result.
+# Set mtime to 1990 to make sure the project won't rebuilt.
+#
+# .. [1] https://github.com/sphinx-doc/sphinx/blob/5.x/sphinx/builders/html/__init__.py#L417
+echo Fixing timestamp of HTML theme
+site_packages_dir=$(python -c 'import site; print(site.getsitepackages()[0])')
+echo Python site-packages directory: $site_packages_dir
+for i in $(find $site_packages_dir -name '*.html'); do
+    touch -m -t 190001010000 $i
+    echo Fixing timestamp of $i
+done
+
+echo Restoring timestamp of git repository
+git_restore_mtime=$action_dir/git-restore-mtime
+$git_restore_mtime $repo_dir
+
+echo ::endgroup::
+
+echo ::group:: Creating build directory
+build_dir=/tmp/sphinxnotes-pages
+mkdir -p $build_dir || true
+echo Temp directory \"$build_dir\" is created
+
+echo ::group:: Running Sphinx builder
+if ! sphinx-build -b html $INPUT_SPHINX_BUILD_OPTIONS "$doc_dir" "$build_dir"; then
+    # See: https://github.com/sphinx-notes/pages/issues/28
+    # echo ::endgroup::
+    # echo ::group:: Dumping Sphinx error log
+    # for l in $(ls /tmp/sphinx-err*); do
+    #     cat $l
+    # done
+    exit 1
+fi
+echo ::endgroup::
+
+echo "artifact=$build_dir" >> $GITHUB_OUTPUT

.github/workflows/sphinx-notes-mod.yml

@@ -0,0 +1,125 @@
+# 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@v3
+      if: ${{ inputs.checkout == 'true' && inputs.cache == 'true' }}
+      with:
+        submodules: recursive
+        fetch-depth: 0 # Required by git-restore-mtime
+    - name: Checkout
+      uses: actions/checkout@v3
+      if: ${{ inputs.checkout == 'true' && inputs.cache == 'false' }}
+
+    - name: Setup python
+      uses: actions/setup-python@v4
+      if: ${{ inputs.cache == 'true' }}
+      with:
+        python-version: ${{ inputs.python_version }}
+        cache: 'pip'
+    - name: Setup python
+      uses: actions/setup-python@v4
+      if: ${{ inputs.cache == 'false' }}
+      with:
+        python-version: ${{ inputs.python_version }}
+
+    - name: Restore cache
+      uses: actions/cache@v3
+      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 }}
+
+    - id: build
+      name: Build documentation
+      run: ./.github/workflows/sphinx-notes-mod.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@v2
+      if: ${{ inputs.publish == 'true' }}
+
+    - name: Fix file permissions
+      shell: sh
+      if: runner.os == 'Linux'
+      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@v1
+      if: ${{ inputs.publish == 'true' }}
+      with:
+        path: ${{ steps.build.outputs.artifact }}
+
+    - id: deployment
+      name: Deploy to GitHub Pages
+      uses: actions/deploy-pages@v2
+      if: ${{ inputs.publish == 'true' }}