Skip to content

Instantly share code, notes, and snippets.

Last active February 6, 2024 20:33
Show Gist options
  • Save mcejp/6b9fbd23028b515399dcf618f2545fe5 to your computer and use it in GitHub Desktop.
Save mcejp/6b9fbd23028b515399dcf618f2545fe5 to your computer and use it in GitHub Desktop.
My baseline setup for Python package projects

Initializing project

Use this as a setup.cfg template: (grab also the pyproject.toml)

TODO: Migrate to using pyproject.toml only

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

Avoid these outdated mechanisms

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/ (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{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

  • 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
name: GitHub Pages
# Runs on pushes targeting the default branch
branches: ["master"]
# Allows you to run this workflow manually from the Actions tab
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
contents: read
pages: write
id-token: write
# Allow one concurrent deployment
group: "pages"
cancel-in-progress: true
runs-on: ubuntu-22.04
- 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
runs-on: ubuntu-latest
needs: build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment