Skip to content

Latest commit

 

History

History
86 lines (71 loc) · 2.16 KB

README.md

File metadata and controls

86 lines (71 loc) · 2.16 KB

auto-sphinx-page-action

GitHub action that creates website using Sphinx.

This action creates a website from your repository, by building with Sphinx.

Features

  • Set up the configuration of Sphinx automatically.
  • Use README as the homepage if index does not exist at the root level.
  • Use PyData theme.
  • Support MyST Markdown. For more information, see MyST-Parser.
  • Publish to GitHub Pages.
  • Can customize with conf.py.

Usage

Refer to the GitHub docs to enable publishing to GitHub Pages.

Set up a workflow in Actions. An example .yml file is as below.

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - master

jobs:
  build-deploy:
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - id: deployment
        uses: yuanx749/auto-sphinx-page-action@main
        with:
          project: "project"  # project's name, optional, default repository name
          author: "author"  # author name, optional, default username

Or use a reusable workflow:

on:
  workflow_dispatch:
  push:

jobs:
  build-deploy:
    permissions:
      pages: write
      id-token: write
    uses: yuanx749/auto-sphinx-page-action/.github/workflows/main.yml@main

For repository with customized docs folder:

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  build-deploy:
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - id: deployment
        uses: yuanx749/auto-sphinx-page-action@main
        with:
          sourcedir: "docs"  # source directory, optional, default .
          requirements: "docs/requirements.txt"  # path to the requirements file, optional