Skip to content
globe

GitHub Action

Sphinx Publisher

1.3.1 Latest version

Sphinx Publisher

globe

Sphinx Publisher

Deploy Sphinx source files as Github Pages. Multi-languages can be handled by providing langs

Installation

Copy and paste the following snippet into your .yml file.

              
- name: Sphinx Publisher

              
  uses: Kjuly/[email protected]
Learn more about this action in Kjuly/sphinx-publisher

Choose a version

sphinx-publisher

Github Action to deploy Sphinx source files as Github Pages.

A template (sphinx-template) is available as a demo.

Configurations

Input Default Description
source_root docs/source Root directory of source to build.
build_root docs/build Root directory for build output.
default_lang en The default language, which will be placed under the build directory, no subdirectory will be created.
lang_mappings '' Newline-separated list of folder & language mappings to build (refer to Multiple languages. If you don't provide one, will use Makefile's SOURCEDIR & BUILDDIR to determine.

Usage

One language only

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  publish:
    name: Publish Sphinx Pages
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Publish Pages
        id: deployment
        uses: Kjuly/sphinx-publisher@main

Folder structure:

docs/
    source/
    build/

Multiple languages

...
uses: Kjuly/sphinx-publisher@main
with:
  default_lang: en
  lang_mappings: |-
    en:en
    zh-Hans:zh_CN

Folder structure:

docs/
    source/
        en/
        zh-Hans/
    build/

Share & Override Config File

You can provide _conf.py to share and override conf.py. Below is a sample folder structure:

source/
    _conf.py  # Shared base config file.

    en/
        _conf.py  # Override config file for "en".
        conf.py   # The final generated config file for "en", which will be updated for each build process.
        ...       #   You don't need to provide it manually.

    zh-Hans/
        conf.py   # No "_conf.py" provided at the same level, will use "conf.py" as it was.
        ...
build/

If you just want to build pages and deploy to other page hosts, you can use Sphinx Builder.