Refactor build/test harness

Add CONTRIBUTING.md
Replace README.rst with README.md
Add examples to README.md

.coveragerc

@@ -2,6 +2,7 @@
 source = src
 
 [run]
+plugins = Cython.Coverage
 branch = true
 source =
     src

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      - name: Install tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install '.[dev]'
+      - name: Build
+        run: |
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # https://github.com/pypa/gh-action-pypi-publish
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+          verbose: true

.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: test
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 8 * * *"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Format with Black
+        run: black .
+      - name: Lint with Ruff
+        run: ruff .
+
+  py_3x:
+    strategy:
+      fail-fast: false
+      matrix:
+        # https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: [ '3.8', '3.9', '3.10', '3.11', '3.x']
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        # https://github.com/actions/checkout
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        # https://github.com/actions/setup-python
+        with:
+          python-version: ${{ matrix.python }}
+          architecture: x64
+          cache: pip
+      - name: install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e '.[ci]'
+          pip freeze
+      - name: Setup test suite
+        run: tox -vv --notest
+      - name: Run test suite
+        run: tox --skip-pkg-install

.pre-commit-config.yaml

@@ -2,27 +2,28 @@
 #   pre-commit install
 # To update the pre-commit hooks run:
 #   pre-commit install-hooks
-exclude: '^(\.tox|ci/templates|\.bumpversion\.cfg)(/|$)'
+exclude: '^(\.tox|\.bumpversion\.cfg)(/|$)'
 repos:
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: master
-    hooks:
-      - id: trailing-whitespace
-        exclude_types:
-          - c
-      - id: end-of-file-fixer
-        exclude_types:
-          - c
-      - id: debug-statements
-  - repo: https://github.com/timothycrosley/isort
-    rev: master
-    hooks:
-      - id: isort
   - repo: https://github.com/psf/black
-    rev: main
+    rev: 24.1.1
     hooks:
       - id: black
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: master
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "v0.2.1"
+    hooks:
+      - id: ruff
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.15.0
     hooks:
-      - id: flake8
+      - id: pyupgrade
+        args: [ --py38-plus ]
+  - repo: https://github.com/mgedmin/check-python-versions
+    rev: 0.22.0
+    hooks:
+      - id: check-python-versions
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: debug-statements