Princeton-CDH · rlskoeser · May 12, 2026 · Mar 24, 2025 · Mar 24, 2025 · Mar 24, 2025
diff --git a/.github/workflows/check_notebooks.yml b/.github/workflows/check_notebooks.yml
@@ -13,20 +13,20 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: "3.12"
-          cache: 'pip'
-          cache-dependency-path: '**/pyproject.toml'
+          enable-cache: true
+          # uses .python-version if not specified
 
       - name: Install package with notebook dependencies
-        run: pip install -e ".[notebooks]"
+        run: uv sync --extra notebooks
 
       # copy notebook config file to current directory
       - name: Check jupyter notebooks with treon
         run: cp notebooks/sample_data/test_config.yml ./corppa_config.yml
 
       # run treon to confirm that notebooks run with current code
       - name: Check jupyter notebooks with treon
-        run: treon notebooks/excerpt_overlap_review.ipynb notebooks/poetry_excerpt_review.ipynb
+        run: uv run treon notebooks/excerpt_overlap_review.ipynb notebooks/poetry_excerpt_review.ipynb
diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ["3.11", "3.12"]
+        python: ["3.12", "3.13"]
     defaults:
       run:
         working-directory: .
@@ -23,28 +23,17 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python }}
-
-      # base the python cache on the hash of all pyproject.toml,
-      # which includes python requirements.
-      # if any change, the cache is invalidated.
-      - name: Cache pip
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: pip-${{ hashFiles('pyproject.toml') }}
-          restore-keys: |
-            pip-${{ hashFiles('pyproject.toml') }}
-            pip-
+          enable-cache: true
 
       - name: Install dependencies
-        run: pip install -e ".[test]"
+        run: uv sync --extra test
 
       - name: Run pytest
-        run: pytest --cov=corppa --cov=test --cov-report=xml
+        run: uv run pytest --cov=corppa --cov=test --cov-report=xml
 
       - name: Upload test coverage to Codecov
         uses: codecov/codecov-action@v4

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -7,5 +7,10 @@ repos:
     rev: v0.3.4
     hooks:
       - id: ruff
-        args: [ --select, I, --fix, --exit-non-zero-on-fix ]
+        args: [ --fix, --exit-non-zero-on-fix ]
       - id: ruff-format
+  # validate GitHub Actions workflow files
+  - repo: https://github.com/mpalmer/action-validator
+    rev: v0.8.0
+    hooks:
+      - id: action-validator
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,34 @@
 # CHANGELOG
 
-## 0.4.0
+## [0.5] 2026-05-12
+
+Updates to support publication of PPA found poems v0.5 dataset
+
+### Poetry Detection 
+- Logic for managing poetry detection configuration for reference corpora 
+  and found poems dataset compilation; a sample config file is provided
+  - Compile dataset script uses config file to combine excerpts and 
+    metadata (poem and PPA) for publishable dataset
+  - `merge_excerpts` method now combines any excerpts with matching
+    spans in PPA text; conflicting poem ids are preserved in `alt_poem_ids`
+  - Poem metadata now supports optional `cluster_id` for known duplicates
+- ReferenceCorpus classes for a consistent way to access reference corpora
+  metadata and text
+- New utility methods for working with PPA metadata when compiling or loading excerpt data
+  in `corppa.poetry_dection.ppa_works`
+- Now supports building text corpus from tar.gz file in addition to directory of text files
+- Update `run_passim` script to use same corppa-specific defaults for command line and `run_passim` method
+- Includes new marimo notebooks for exploring found poems excerpt data
+
+### Misc
+- Now supports and tested against both Python 3.12 and 3.13; dropped support for 3.11
+- Now using uv for GitHub Actions and local development
+- Added pre-commit hook to validate GitHub Actions workflow files
+- Sphinx code documentation split out into files matching python modules 
+- Experimental scripts to subset excerpt data and upload to Grist 
+- Configured intentionally untested code to be exempted from code coverage (CH TML parsing)
+
+## [0.4] 2025-04-30
 - Now supports and tested against both Python 3.11 and 3.12
 - Now licensed under Apache 2
 ### Documentation
@@ -35,7 +63,7 @@
 - Increased use of Python type hinting
 - Configured codecov with separate reporting for tests and whole project, with different targets for coverage
 
-## 0.3.0
+## [0.3] 2024-11-01
 - New dependency: intspan
 ### Poetry Detection
 - New Prodigy recipe for adjudicating text annotations
@@ -45,7 +73,7 @@
 ### Misc
 - Fixed Codecov integration
 
-## 0.2.0
+## [0.2] 2024-10-07
 - Now requires Python 3.12
 ### Corppa Utilities
 - Basic readme documentation for filter script
@@ -64,8 +92,15 @@
 - Ruff precommit hook now configured to autofix import order
 
 
-## 0.1.0
+## [0.1] 2024-06-05
 - Utility to filter the full text corpus by source ID
 - Experimental Scripts
   - OCR evaluation
   - Character-level statistics
+
+
+[0.1]: https://github.com/Princeton-CDH/corppa/releases/tag/0.1
+[0.2]: https://github.com/Princeton-CDH/corppa/releases/tag/0.2
+[0.3]: https://github.com/Princeton-CDH/corppa/releases/tag/0.3
+[0.4]: https://github.com/Princeton-CDH/corppa/releases/tag/0.4
+[0.5]: https://github.com/Princeton-CDH/corppa/releases/tag/0.5
diff --git a/codecov.yml b/codecov.yml
@@ -11,6 +11,6 @@ coverage:
       tests:  # declare a new status context  for "tests"
         target: 100%  # we always want 100% coverage here
         paths:
-          - "test/"  # only include coverage in "tests/" folder
+          - "tests/"  # only include coverage in "tests/" folder
 
 
diff --git a/docs/source/LICENSE.md b/docs/source/LICENSE.md
@@ -0,0 +1,7 @@
+---
+orphan: true
+---
+```
+{include} ../../LICENSE.md
+```
+
diff --git a/docs/source/code-docs.rst b/docs/source/code-docs.rst
diff --git a/docs/source/code-docs/annotation.rst b/docs/source/code-docs/annotation.rst
@@ -0,0 +1,30 @@
+Annotation
+##########
+
+Data Preparation
+================
+
+Preliminary Page Set Creation
+------------------------------
+.. automodule:: corppa.poetry_detection.annotation.create_pageset
+.. Note: not including members for method docs, only top-level script usage
+
+Add Metadata
+------------
+.. automodule:: corppa.poetry_detection.annotation.add_metadata
+.. Note: not including members for method docs, only top-level script usage
+
+Annotation Recipes
+==================
+.. automodule:: corppa.poetry_detection.annotation.annotation_recipes
+.. Note: not including members for method docs, only top-level script usage
+
+Command Recipes
+===============
+.. automodule:: corppa.poetry_detection.annotation.command_recipes
+.. Note: not including members for method docs, only top-level script usage
+
+Process Adjudication Data
+=========================
+.. automodule:: corppa.poetry_detection.annotation.process_adjudication_data
+.. Note: not including members for method docs, only top-level script usage
diff --git a/docs/source/code-docs/index.rst b/docs/source/code-docs/index.rst
@@ -0,0 +1,10 @@
+Code Documentation
+##################
+
+.. toctree::
+   :maxdepth: 2
+
+   ocr
+   utils
+   annotation
+   poetry-detection
diff --git a/docs/source/code-docs/ocr.rst b/docs/source/code-docs/ocr.rst
@@ -0,0 +1,12 @@
+OCR
+###
+
+.. automodule:: corppa.ocr.gvision_ocr
+  :members:
+
+
+Collate Texts
+=============
+.. automodule:: corppa.ocr.collate_txt
+.. Note: not including the members for the method docs, *but* we should we
+.. make the top-level comment better.
diff --git a/docs/source/code-docs/poetry-detection.rst b/docs/source/code-docs/poetry-detection.rst
@@ -0,0 +1,29 @@
+Poetry Detection
+################
+
+Core objects
+============
+
+.. automodule:: corppa.poetry_detection.core
+  :members:
+
+Reference Corpora
+=================
+.. automodule:: corppa.poetry_detection.ref_corpora
+  :members:
+
+
+
+Scripts
+=======
+
+refmatcha
+---------
+
+.. automodule:: corppa.poetry_detection.refmatcha
+
+Merge excerpts
+--------------
+
+.. automodule:: corppa.poetry_detection.merge_excerpts
+  :members:
diff --git a/docs/source/code-docs/utils.rst b/docs/source/code-docs/utils.rst
@@ -0,0 +1,27 @@
+Utils
+#####
+
+Filter Utility
+==============
+.. automodule:: corppa.utils.filter
+.. Note: not including members for method docs, only top-level script usage
+
+Path Utilities
+==============
+.. automodule:: corppa.utils.path_utils
+  :members:
+
+Generate PPA Page Set
+=====================
+.. automodule:: corppa.utils.generate_page_set
+.. Note: not including members for method docs, only top-level script usage
+
+Add Image (Relative) Paths
+==========================
+.. automodule:: corppa.utils.add_image_relpaths
+.. Note: not including members for method docs, only top-level script usage
+
+Build Text Corpus
+=================
+.. automodule:: corppa.utils.build_text_corpus
+.. Note: not including members for method docs, only top-level script usage
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -9,7 +9,7 @@
 from corppa import __version__
 
 project = "corppa"
-copyright = "2024,2025 Center for Digital Humanities, Princeton University"
+copyright = "2024—2026 Center for Digital Humanities, Princeton University"
 author = "Center for Digital Humanities RSE Team, Princeton University"
 release = __version__
 
@@ -65,6 +65,3 @@
         "sidebar_footer.html",
     ],
 }
-
-
-