Overview

yardang is a tool to configure the most common Sphinx options directly from a pyproject.toml. Sphinx relies on a conf.py file and Makefiles, but these usually overlap a substantial amount with information already stored in the repository (e.g. in the pyproject.toml). Within an organization, these files tend to include a substantial amount of overlapping information.

Integrations

yardang takes the most important parts, like theme, title, pages, etc, and extracts them directly from the pyproject.toml. It creates a temporary file for the conf.py, and builds the project into docs/html. Out of the box, it comes with support for several popular Sphinx frameworks:

• Sphinx Design

• Myst Markdown

• Sphinx AutoAPI

• Autodoc Pydantic

• Furo Theme

Usage

yardang builds Sphinx via a CLI, which will build docs into docs/html:

yardang build

GitHub Pages

The goal of this project is to make it as easy as possible to use Sphinx. The following yaml should be all it takes to integrate your project with GitHub Pages, without changing anything in your existing repository.

name: Docs
on:
  push:
    branches: ["main"]
    tags: ["v*"]
    paths-ignore: ["LICENSE", "README.md"]
permissions:
    contents: write
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions-ext/yardang@main
        with:
        token: ${{ secrets.GITHUB_TOKEN }}