Helps you deploy your Sphinx documentation to Github Pages.

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.

1. Set the publishing sources to "Github Actions"

2. Create the following workflow:

   name: Deploy Sphinx documentation to Pages
   
   on:
     push:
       branches: [master] # branch to trigger deployment
   
   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

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:

   name: Deploy Sphinx documentation to Pages
   
   on:
     push:
       branches: [master] # branch to trigger deployment
   
   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 }}

In most cases you don't need to know about the following inputs. Unless you need to highly customize the action's behavior.

The following repository's pages are built by this action:

• https://github.com/SilverRainZ/bullet
• https://github.com/sphinx-notes/pages
• https://github.com/sphinx-notes/lilypond
• https://github.com/sphinx-notes/strike
• and more...

You can find the workflow file in the above repositories.

Use Sphinx confval html_extra_path.

It is useful when you have pushed a new commit to remote but the job of the previous commit is not finished yet. See concurrency for more details.

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

For python dependencies, just add them to your requirements.txt or pyproject.toml file.

For non-python dependencies, add a step to your workflow file, and install them with the appropriate tools (such as apt, wget, ...). See #24 for example.

Repository is automatically checkout by default, but some user may need to customize checkout options (For example, checkout private repository, checkout multiple repositories). For this case, user can set the checkout options to false, then use action/checkout byeself.

steps:
- uses: actions/checkout@master
  with:
    YOUR_CUSTOM_OPTIONS: ...
- id: deployment
  uses: sphinx-notes/pages@v3
  with:
    checkout: false