epythet 0.1.15

Tools for documentation and packaging

epythet

Documentation and packaging tools. Less humdrum, more automation, earlier at the pub.

Full documentation here generated by Epythet.

Getting Started

Follow the Sphinx Installation Guide

pip install epythet

Follow the short Quickstart Guide

About

Tired of learning new frameworks and just need something to quickly display your docstrings in your python files? You've come to the right place. Epythet is built on Sphinx Python Documentation Generator but automatically generates pages for each module .py files and a table of contents.

Publishing to GitHub Pages with GitHub Actions

Step 1: Add the CI workflow

Add workflow .github/workflows/publish-docs.yml to your repo and modify the trigger conditions to suit your needs. Example below will run automatically when the other "Continuous Integration" workflow is completed.

name: GitHub Pages

on:
  workflow_run:
    workflows: ["Continuous Integration"]
    types:
      - completed

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: i2mint/epythet/actions/publish-github-pages@master
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          docs-branch: "gh-pages"
          docs-dir: "./docsrc/_build/html/"
          python-version: "3.10"

Step 2: Enable GitHub Pages

After the CI runs and creates the gh-pages branch, you need to tell GitHub to actually serve it. There are two ways to do this:

The clicky way (for those who enjoy navigating settings menus)

Go to your repo's Settings > Pages, set the source branch to gh-pages and the folder to / (root), then click Save.

The fast way (for those who value their time)

If you have the gh CLI installed:

# Check if Pages is set up correctly
epythet check-pages owner/repo

# Enable or fix Pages configuration
epythet configure-pages owner/repo

Or from Python:

from epythet import check_pages_setup, enable_pages

# Diagnose
check_pages_setup('owner/repo')

# Fix
enable_pages('owner/repo')

You can also point these at a local git checkout instead of owner/repo:

epythet check-pages .
epythet configure-pages /path/to/my/project

These tools work with either the gh CLI (recommended) or a GITHUB_TOKEN environment variable.

Under the hood, configure-pages is just the GitHub Pages REST API — the direct gh equivalent of Settings > Pages → Branch gh-pages, folder / (root) → Save is:

# POST creates the Pages site (when Pages is not yet enabled — GitHub's default);
# use -X PUT instead to change an already-enabled Pages config.
gh api repos/owner/repo/pages -X POST -f 'source[branch]=gh-pages' -f 'source[path]=/'

See CI epythet troubleshooting.