Merge pull request #13 from sphinx-notes/cache2

Support incremental build
sphinx-notes · Dec 4, 2022 · cb9ee3e · cb9ee3e
2 parents 59fd421 + 1c18b98
commit cb9ee3e
Show file tree

Hide file tree

Showing 6 changed files with 752 additions and 143 deletions.
diff --git a/README.rst b/README.rst
@@ -1,5 +1,5 @@
 =========================
-Sphinx to GitHub Pages V2
+Sphinx to GitHub Pages V3
 =========================
 
 .. image:: https://img.shields.io/github/stars/sphinx-notes/pages.svg?style=social&label=Star&maxAge=2592000
@@ -10,64 +10,58 @@ Help you deploying your Sphinx documentation to Github Pages.
 Usage
 =====
 
-This action only help you build and commit Sphinx documentation to ``gh-pages``,
-branch. So we need some other actions:
-
-- ``action/setup-python`` for installing python and pip
-- ``actions/checkout`` for checking out git repository
-- ``ad-m/github-push-action`` for pushing site to remote
-
-So your workflow file should be:
-
-.. code-block:: yaml
-
-   name: Pages
-   on:
-     push:
-       branches:
-       - master
-   jobs:
-     build:
-       runs-on: ubuntu-latest
-       steps:
-       - uses: actions/setup-python@v2
-       - uses: actions/checkout@master
-         with:
-           fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
-       - name: Build and Commit
-         uses: sphinx-notes/pages@v2
-       - name: Push changes
-         uses: ad-m/github-push-action@master
-         with:
-           github_token: ${{ secrets.GITHUB_TOKEN }}
-           branch: gh-pages
+1. `Set the publishing sources to "Github Actions"`__
+
+   .. note:: Publishing your GitHub Pages site with GitHub Actions workflow is **in beta and subject to change**.
+
+   __ https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
+
+2. Create workflow:
+
+   .. code-block:: yaml
+
+      name: Deploy Sphinx documentation to Pages
+
+      # Runs on pushes targeting the default branch
+      on:
+        push:
+          branches: [master]
+
+      jobs:
+        pages:
+          runs-on: ubuntu-20.04
+          environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+          permissions:
+            pages: write
+            id-token: write
+          steps:
+          - id: deployment
+            uses: sphinx-notes/pages@v3
 
 Inputs
 ======
 
-======================= ============== ============ =============================
-Input                   Default        Required     Description
------------------------ -------------- ------------ -----------------------------
-``documentation_path``  ``'./docs'``   ``false``    Relative path under
-                                                    repository to documentation
-                                                    source files
-``target_branch``       ``'gh-pages'`` ``false``    Git branch where assets will
-                                                    be deployed
-``target_path``          ``'.'``        ``false``   Directory in Github Pages
-                                                    where Sphinx Pages will be
-                                                    placed
-``repository_path``     ``'.'``        ``false``    Relative path under
-                                                    ``$GITHUB_WORKSPACE`` to
-                                                    place the repository.
-                                                    You not need to set this
-                                                    Input unless you checkout
-                                                    the repository to a custom
-                                                    path
-``requirements_path``   ``''``         ``false``    Relative path under
-                                                    ``$repository_path`` to pip
-                                                    requirements file
-``sphinx_version``      ``''``         ``false``    Custom version of Sphinx
-======================= ============== ============ =============================
+======================= ================================ ======== =============================
+Input                   Default                          Required Description
+----------------------- -------------------------------- -------- -----------------------------
+``documentation_path``  ``./docs``                       false    Path to Sphinx source files
+``requirements_path``   ``./docs/requirements.txt``      false    Path to to requirements file
+``python_version``      ``3.10``                         false    Version of Python
+``sphinx_version``      ``5.3``                          false    Version of Sphinx
+``cache``               ``false``                        false    Enable cache to speed up
+                                                                  documentation building
+======================= ================================ ======== =============================
+
+Outputs
+=======
+
+======================= ======================================================================
+Output                   Description
+----------------------- ----------------------------------------------------------------------
+``page_url``            URL to deployed GitHub Pages
+======================= ======================================================================
 
 Examples
 ========

diff --git a/action.yml b/action.yml
@@ -7,30 +7,82 @@ branding:
   icon: 'upload-cloud'
 inputs:
   documentation_path:
-    description: 'Relative path under $repository_path to documentation source files'
+    description: 'Path to Sphinx source files'
     required: false
     default: './docs'
-  target_branch:
-    description: 'Git branch where Github Pages will be deployed'
-    required: false
-    default: 'gh-pages'
-  target_path:
-    description: 'Path in Github Pages where Sphinx Pages will be placed'
-    required: false
-    default: '.'
-  repository_path:
-    description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
-    required: false
-    default: '.'
   requirements_path:
-    description: 'Relative path under $repository_path to pip requirements file'
+    description: 'Path to requirements file'
     required: false
-    default: './requirements.txt'
+    default: './docs/requirements.txt'
+  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
+outputs:
+  page_url:
+    description: 'URL to deployed GitHub Pages'
+    value: ${{ steps.deployment.outputs.page_url }}
 
 runs:
-  using: 'node12'
-  main: 'main.js'
+  using: "composite"
+  steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      if: ${{ inputs.cache == 'true' }}
+      with:
+        fetch-depth: 0 # Required by git-restore-mtime
+    - name: Checkout
+      uses: actions/checkout@v3
+      if: ${{ 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 }}
+
+    - 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_SPHINX_VERSION: ${{ inputs.sphinx_version }}
+        INPUT_CACHE: ${{ inputs.cache }}
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v2
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v1
+      with:
+        path: /tmp/sphinxnotes-pages
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v1