Modernize starterkit-ci: uv-based CI, stronger tests, and workflow/dependency automation

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10

.github/workflows/integration.yml

@@ -0,0 +1,54 @@
+name: integration
+
+on:
+  workflow_dispatch:
+    inputs:
+      starterkit_repo:
+        description: "Repository to test (owner/name)"
+        required: false
+        default: "lhcb/starterkit-lessons"
+      starterkit_ref:
+        description: "Branch or tag to test"
+        required: false
+        default: "master"
+  schedule:
+    - cron: "0 3 * * 1"
+
+concurrency:
+  group: integration-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  starterkit-real-repo:
+    name: Real Starterkit Repo
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install starterkit-ci
+        run: uv sync --frozen
+
+      - name: Clone Starterkit Repository
+        run: |
+          git clone \
+            --depth 1 \
+            --branch "${{ inputs.starterkit_ref || 'master' }}" \
+            "https://github.com/${{ inputs.starterkit_repo || 'lhcb/starterkit-lessons' }}.git" \
+            starterkit-lessons
+
+      - name: Build docs
+        run: uv run starterkit-ci build --source-dir starterkit-lessons
+
+      - name: Run link checks
+        run: uv run starterkit-ci check --source-dir starterkit-lessons

.github/workflows/prek.yml

@@ -0,0 +1,18 @@
+name: prek
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  prek:
+    name: Run prek hooks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: j178/prek-action@v1

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Build and Publish to PyPI
 on:
   push:
     branches:
-      - main
+      - master
     tags:
       - '*'
   pull_request:
@@ -15,23 +15,23 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          python-version: "3.13"
 
-      - name: Install build dependencies
-        run: python -m pip install --upgrade pip build
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
 
       - name: Build distribution
-        run: python -m build
+        run: uv build --no-sources
 
       - name: Store distribution packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: python-package-distributions
           path: dist/
@@ -49,7 +49,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution packages
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: python-package-distributions
           path: dist/

.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  tests:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --frozen --group test
+
+      - name: Run tests
+        run: uv run pytest

.pre-commit-config.yaml

@@ -1,4 +1,20 @@
+ci:
+  autofix_prs: true
+  autoupdate_schedule: weekly
+  autoupdate_commit_msg: "chore(pre-commit): pre-commit autoupdate"
+
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.1
     hooks:

README.md

@@ -1 +1,100 @@
-# Starterkit CI Helpers
+# starterkit-ci
+
+Helpers and Sphinx configuration for building and checking the LHCb Starterkit lessons documentation.
+
+This package provides:
+- A CLI command, `starterkit-ci`, to run Sphinx build/linkcheck in a consistent way.
+- Shared Sphinx configuration under `starterkit_ci.sphinx_config`.
+- Custom Sphinx transforms used by Starterkit lesson content.
+
+## Installation
+
+With `uv`:
+
+```bash
+uv add starterkit-ci
+```
+
+With `pip`:
+
+```bash
+pip install starterkit-ci
+```
+
+For local development in this repository:
+
+```bash
+uv sync --frozen --group dev
+```
+
+## CLI usage
+
+The package exposes a console script: `starterkit-ci`.
+The legacy alias `starterkit_ci` is still available for compatibility.
+
+### Build docs
+
+```bash
+starterkit-ci build --source-dir /path/to/docs
+```
+
+### Check external links
+
+```bash
+starterkit-ci check --source-dir /path/to/docs
+```
+
+### Clean Sphinx build output
+
+```bash
+starterkit-ci clean --source-dir /path/to/docs
+```
+
+By default warnings are treated as errors (`-W`). To allow warnings:
+
+```bash
+starterkit-ci build --source-dir /path/to/docs --allow-warnings
+```
+
+### Run without installing (uvx)
+
+You can run the tool directly from PyPI without adding it to your environment:
+
+```bash
+uvx starterkit-ci build --source-dir /path/to/docs
+uvx starterkit-ci check --source-dir /path/to/docs
+```
+
+## Using the shared Sphinx config
+
+In a docs project `conf.py`:
+
+```python
+from starterkit_ci.sphinx_config import *  # NOQA
+```
+
+You can then extend settings in your project, for example:
+- `starterkit_ci_redirects` for HTML redirects.
+- `setup.extra_setup_funcs` for project-specific setup hooks.
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run code quality checks:
+
+```bash
+pre-commit run --all-files
+```
+
+## CI and releases
+
+- `pre-commit` hooks run in GitHub Actions via `prek`.
+- Unit tests run on Python 3.10 to 3.14.
+- Integration workflow validates against the real `lhcb/starterkit-lessons` repository.
+- Package builds use `uv build`.
+- PyPI publishing uses trusted publishing on tags.

pyproject.toml

@@ -11,7 +11,7 @@ dynamic = ["version"]
 
 description = "Helpers for Starterkit Continuous Integration"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 
 license = "BSD-3-Clause"
 license-files = ["LICENSE"]
@@ -25,10 +25,11 @@ keywords = ["Starterkit"]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.8",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
 ]
 
 dependencies = [
@@ -38,12 +39,28 @@ dependencies = [
   "nbsphinx>=0.9",
 ]
 
+[dependency-groups]
+test = [
+  "pytest>=8.4",
+  "pytest-cov>=5.0",
+]
+lint = [
+  "pre-commit>=4.0",
+  "ruff>=0.15.0",
+  "ty>=0.0.17",
+]
+dev = [
+  {include-group = "test"},
+  {include-group = "lint"},
+]
+
 [project.urls]
 "Homepage" = "https://github.com/lhcb/starterkit-ci"
 "Bug Reports" = "https://github.com/lhcb/starterkit-ci/issues"
 "Source" = "https://github.com/lhcb/starterkit-ci"
 
 [project.scripts]
+starterkit-ci = "starterkit_ci:parse_args"
 starterkit_ci = "starterkit_ci:parse_args"
 
 [tool.setuptools]
@@ -67,4 +84,4 @@ local_scheme = "node-and-date"
 max-line-length = 120
 
 [tool.pytest.ini_options]
-addopts = "--cov=cirun --cov-report=term-missing"
+addopts = "--cov=starterkit_ci --cov-report=term-missing"