Document Hosting: GitHub Pages

Introduction

This guide walks you through setting up GitHub Pages to host your project documentation built with Sphinx.

Key Features

  • Host static HTML docs using GitHub Pages

  • Generate documentation with Sphinx + Makefile

  • Automate with GitHub Actions

  • Easy deployment from the main branch

Installation

First, make sure the following tools are installed:

  • Python (>=3.7)

  • uv — used for dependency management

  • Sphinx — documentation generator

To install uv (recommended):

curl -LsSf https://astral.sh/uv/install.sh | sh

Configuration

Makefile

We have to execute quite a number of commands to generate the docs. To make this process easier, let’s create a Makefile.

Makefile
.PHONY: help docs
.DEFAULT_GOAL := help

define BROWSER_PYSCRIPT
import os, webbrowser, sys
from urllib.request import pathname2url
webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
endef
export BROWSER_PYSCRIPT

define PRINT_HELP_PYSCRIPT
import re, sys
for line in sys.stdin:
    match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
    if match:
        target, help = match.groups()
        print("%-20s %s" % (target, help))
endef
export PRINT_HELP_PYSCRIPT

BROWSER := python -c "$$BROWSER_PYSCRIPT"

help:  ## Show this help message
    @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)

docs:  ## generate Sphinx HTML documentation, including API docs
    rm -f docs/pyfoundry*.rst
    sphinx-apidoc -o docs/ pyfoundry
    $(MAKE) -C docs clean
    $(MAKE) -C docs html
    $(BROWSER) docs/_build/html/index.html

GitHub Actions Workflow

Add the following to .github/workflows/docs.yml:

name: Documentation

on:
  push:
    branches:
      - main

jobs:
  document:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install sphinx sphinx-rtd-theme toml

      - name: Generate Docs
        run: make docs

      - name: Deploy docs to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html
          allow_empty_commit: true
          keep_files: true

Usage

  1. Commit and push the changes to a branch.

  2. Create a pull request and merge it into main.

  3. Once merged, go to the Actions tab and verify the Documentation job succeeds.

  4. Then: - Go to your repository Settings - Scroll to GitHub Pages - Set Source to Branch: gh-pages - Click Save - Your docs should now be live at:

Additional Resources

Next Step

Next, we will prepare to publish the package to PyPI. 🎯