yousefmoazzam / pages

Github Actions for publishing Sphinx HTML output to github pages

Sphinx to GitHub Pages

The project is originated from seanzhengw/sphinx-pages, it helps you building Sphinx documentation and commit specified branch.

Usage

Note

You should enable extension sphinx.ext.githubpages in your conf.py first.

The simplpest Workflow file looks like that:

- name: Build and Commit
  uses: sphinx-notes/pages@master

But note that this actions only help you build and commit Sphinx documentation, we need another tow actions: one for checking out and one for push to remote, so your workflow file should be:

name: Pages
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      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@master
    - name: Push changes
      uses: ad-m/github-push-action@master
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        branch: gh-pages

Inputs

target_branch:	(default: 'gh-pages') Git branch where assets will be deployed
repository_path:	(default: '.') Relative path under $GITHUB_WORKSPACE to place the repository
documentation_path:	(default: '.') Relative path under repository to documentation source files
install_requirements:	(default: 'true') Install Sphinx extensions listed in $documentation_path/requirements.txt, symbol link is supported
extra_files:	(default: '') Extras files(such as README, LICENSE) to be commited to $target_branch

Examples

The following pages are built by this action:

• https://sphinx-notes.github.io/pages
• https://sphinx-notes.github.io/lilypond
• https://sphinx-notes.github.io/any
• https://sphinx-notes.github.io/strike
• You can visit https://sphinx-notes.github.io for more pages...

You can found the workflow file in their corrsponding repository.