Developer Notes

This repo uses git-flow branching conventions; main contains the most recent release, and work in progress will be on the develop branch. Pull requests for new features should be made against develop.

Developer setup and installation

  • Recommended: create a python virtual environment with your tool of choice (virtualenv, conda, etc); use python 3.12 or higher

  • Install the local checked out version of this package in editable mode (-e), including all python dependencies and optional dependencies for development and testing:

pip install -e ".[dev]"

  • This repository uses pre-commit for python code linting and consistent formatting. Run this command to initialize and install pre-commit hooks:

pre-commit install

  • Copy sample_config.yml to corppa_config.yml and edit paths and configurations for your local environment.

Documentation

Documentation is generated by using sphinx. To generate the documentation, first install the development requirements.

pip install -e ".[dev]"

Then the documentation can be built using the customized makefile in the docs directory.

cd docs
make html

To check documentation coverage, run:

make html -b coverage

This will create a file under _build/coverage/python.txt listing any Python classes or methods that are not documented. Note that sphinx can only report on code coverage for files that are included in the documentation. If a new Python file is created but not included in the sphinx documentation, it will be omitted.

License notice in file headers

A copyright notice has been applied to the header of all files with copywrite with the project configuration in .copywrite.hcl.

To install with brew:

brew tap hashicorp/tap
brew install hashicorp/tap/copywrite

Once installed, you can apply the copyright notice to all files without this notice by running copywrite headers (note that it does not update existing files even if the configuration has changed).

Notebooks

For notebooks, authorship and copyright information should be added manually. The following template was used for existing notebooks within the first cell.

# [Title]
By [Authors]

(c)2025 Trustees of Princeton University. Permission granted for non-commercial distribution online under the [Apache 2.0 License](https://github.com/Princeton-CDH/corppa/blob/feature/license-headers/LICENSE).