Development¶

Set up the repository with uv:

uv sync

Run the test suite:

uv run pytest

Build the package locally when you need to inspect the distribution artifacts:

uv build

Publishing to PyPI is handled by GitHub Actions. Push release-worthy changes to main or run the Publish to PyPI workflow manually. The workflow runs Python Semantic Release to stamp the next version, update uv.lock, create the Git tag and GitHub Release, build the package with uv build, and upload the distribution artifacts to PyPI using trusted publishing. Local uv publish is not part of the release process.

If a release tag already exists but has not been uploaded to PyPI, run the Publish to PyPI workflow manually and set ref to that tag, such as v0.1.1. The workflow will check out the tag, build the package, and publish those artifacts without asking Python Semantic Release to calculate another version.

Published versions must have matching Git tags in the remote repository so Python Semantic Release can find the correct baseline. The current release is 0.1.1, so keep v0.1.1 available before running the workflow; without that tag, it can calculate the next version from an older release point.

Build the documentation locally:

python -m pip install -r docs/requirements.txt
sphinx-build -b html -E docs/source docs/build/html

If the local environment has locale-related Sphinx startup errors, retry with a plain C locale:

LC_ALL=C LANG=C sphinx-build -b html -E docs/source docs/build/html

Read the Docs builds the documentation from the repository using its project configuration and .readthedocs.yaml. Keep that file in sync with the local documentation build requirements when dependencies or build settings change. The Read the Docs project is configured to update only when files under docs change; that trigger rule is managed in Read the Docs, not in this repository.

Documentation should describe the actual command-line behavior and Python API in src/scrape_smith. When a new tool is added, update the CLI reference, add a tool page, and include API coverage where the public functions are meant to be used directly.