My baseline setup for Python package projects

_README.md

Initializing project

Use this as a setup.cfg template: https://github.com/mcejp/goeieDAG/blob/master/setup.cfg (grab also the pyproject.toml)

TODO: Migrate to using pyproject.toml only

TODO: Remove VERSION constant (see pallets/flask#5230)

Avoid these outdated mechanisms

• distutils
• setup.py

Sphinx API docs

sphinx-quickstart doc
sphinx-apidoc -o doc <package-name>

If you try to build the API docs now, Sphinx will probably not manage to find the package (because "." is not implicitly added to PYTHONPATH unless you execute python -m ...);

this can be worked around by prepending this snippet to doc/conf.py (assuming the Python code is in the root of the repo):

import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))

However, this is not good enough if the package has dependencies of its own. It is better to install the package into the environment before building the docs.

Deployment to GitHub Pages

In https://github.com/{project-path}/settings/pages select GitHub Actions as source.

Download pages.yaml below as .github/workflows/pages.yaml. You might want to review the installed prerequisities (esp. Sphinx themes) and the paths used.

Releasing to PyPI

Prerequisities: the packages build and twine

• update __VERSION__ and CHANGELOG.md

• execute the following commands

  mkdir -p dist
  rm dist/*.tar.gz dist/*.whl
  python -m build
  python -m twine upload --repository testpypi dist/*       # either
  python -m twine upload dist/*                             # or
  

pages.yaml

name: GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

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

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4

      - name: Install package
        run: python3 -m pip install .

      - name: Install Sphinx
        run: python3 -m pip install furo sphinx

      - name: Build docs
        run: sphinx-build -b html doc _site

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1

  # Deployment job
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1