Merge pull request #27 from sphinx-notes/feat/publishing-from-branch

Support publishing from a branch

Author: SilverRainZ

README.rst

@@ -7,25 +7,21 @@ Sphinx to GitHub Pages V3
 
 Helps you deploy your Sphinx documentation to Github Pages.
 
-.. warning:: v3 is **in beta and subject to change**, use v2__ if you need a stable version.
-
-__ https://github.com/sphinx-notes/pages/tree/v2
-
 Usage
 =====
 
+We provides two ways for publishing GitHub pages.
+The first one is the default but **still in beta**, use the second one if you tend to be stable.
+
+Publishing with this action (default)
+***************************************
+
 1. `Set the publishing sources to "Github Actions"`__
-2. Create workflow:
+2. Create the following 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
@@ -41,6 +37,33 @@ Usage
 
 __ 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
 
+Publishing from a branch (classical)
+************************************
+
+1. Create a branch ``gh-pages``
+2. `Set the publishing sources to "Deploy from a branch"`__, then specify the branch just created
+3. Create the following workflow, in this way user need to publish the site by another action,
+   we use `peaceiris/actions-gh-pages`__ here:
+
+   .. code-block:: yaml
+
+      name: Deploy Sphinx documentation to Pages
+      jobs:
+        pages:
+          runs-on: ubuntu-20.04
+          steps:
+          - id: deployment
+            uses: sphinx-notes/pages@v3
+            with:
+              publish: false
+          - uses: peaceiris/actions-gh-pages@v3
+            with:
+              github_token: ${{ secrets.GITHUB_TOKEN }}
+              publish_dir: ${{ steps.deployment.outputs.artifact }}
+
+__ https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch
+__ https://github.com/peaceiris/actions-gh-pages
+
 Inputs
 ======
 
@@ -52,24 +75,39 @@ Input                      Default                      Required Description
                                                                  used in ``pip install -r XXX`` command
 ``pyproject_extras``       ``docs``                     false    Extras of `Requirement Specifier`__
                                                                  used in ``pip install .[XXX]``
+========================== ============================ ======== =================================================
+
+Advanced
+********
+
+In most cases you don't need to know about the following inputs.
+Unless you need to highly customize the action's behavior.
+
+========================== ============================ ======== =================================================
+Input                      Default                      Required Description
+-------------------------- ---------------------------- -------- -------------------------------------------------
 ``python_version``         ``3.10``                     false    Version of Python
 ``sphinx_version``         ``5.3``                      false    Version of Sphinx
 ``sphinx_build_options``                                false    Additional options passed to ``sphinx-build``
 ``cache``                  ``false``                    false    Enable cache to speed up documentation building
 ``checkout``               ``true``                     false    Whether to automatically checkout the repository,
                                                                  if false, user need to do it byself
+``publish``                ``true``                     false    Whether to automatically publish the repository
 ========================== ============================ ======== =================================================
 
 __ https://pip.pypa.io/en/stable/reference/requirement-specifiers/#overview
 
 Outputs
 =======
 
-======================= ============================
+======================= =========================================================
 Output                  Description
------------------------ ----------------------------
-``page_url``            URL to deployed GitHub Pages
-======================= ============================
+----------------------- ---------------------------------------------------------
+``page_url``            URL to deployed GitHub Pages,
+                        only available when option ``publish`` is set to ``true``
+``artifact``            Directory where artifact (HTML documentation) is stored,
+                        user can use it to deploy GitHub Pages manually
+======================= =========================================================
 
 Examples
 ========

action.yml

@@ -38,10 +38,17 @@ inputs:
     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'
+    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"
@@ -77,7 +84,8 @@ runs:
         restore-keys: |
           sphinxnotes-pages-${{ runner.os }}
 
-    - name: Build documentation
+    - id: build
+      name: Build documentation
       run: ${{ github.action_path }}/main.sh
       shell: bash
       env:
@@ -91,12 +99,15 @@ runs:
 
     - name: Setup Pages
       uses: actions/configure-pages@v2
+      if: ${{ inputs.publish == 'true' }}
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v1
+      if: ${{ inputs.publish == 'true' }}
       with:
-        path: /tmp/sphinxnotes-pages
-
-    - name: Deploy to GitHub Pages
-      id: deployment
+        path: ${{ steps.build.outputs.artifact }}
+      
+    - id: deployment
+      name: Deploy to GitHub Pages
       uses: actions/deploy-pages@v1
+      if: ${{ inputs.publish == 'true' }}

main.sh

@@ -3,16 +3,18 @@
 # 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 ::group:: Initialize various paths
 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,
@@ -96,3 +98,5 @@ if ! sphinx-build -b html $INPUT_SPHINX_BUILD_OPTIONS "$doc_dir" "$build_dir"; t
     exit 1
 fi
 echo ::endgroup::
+
+echo "artifact=$build_dir" >> $GITHUB_OUTPUT