citation

Django app to track bibliometric metadata for publications that reference computational models.

Current local runtime baseline:

• Python 3.12
• Django 5.2 LTS
• PostgreSQL 18
• Docker Compose managed services with DB healthchecks
• Dependencies managed with uv via pyproject.toml and uv.lock

Documentation

Documentation is available at Read the Docs

Documentation ownership:

• pyproject.toml — package metadata and runtime dependencies (source of truth)
• README.md — user setup and release workflow
• AGENTS.md — canonical operational specification for agents
• CHANGELOG.md — release history
• docs/source/ — browsable technical documentation (MyST Markdown)
• docs/source/adr/ — architecture decision records (rendered with the docs)

Building documentation locally

Documentation sources live in docs/source/ as MyST Markdown. Build them inside the test container:

docker compose run --rm test bash -lc 'cd /code/docs && make clean html'

Generated HTML lands in docs/build/html/.

Local development

Standard local workflow uses the root Makefile, which wraps docker compose:

./build.sh              # only needed if docker-compose.yml does not exist yet
make clean              # remove containers, networks, and volumes
make build              # build fresh images
make up                 # start services
make test               # build, start PostgreSQL, migrate, and run the test suite
make check              # Django system checks in the container
make migrations-check   # detect migration drift

For other one-off Django commands, run them in the test container:

docker compose run --rm test python -m django <command>

Dependency management (uv)

The project uses uv with PEP 621 metadata in pyproject.toml.

When dependencies change, regenerate and commit uv.lock using the Make target:

make lock

Container builds install dependencies with the committed lockfile via uv sync --locked.

Publish to PyPI

Use the Make target to build and publish from the test container:

PYPI_TOKEN=<pypi-token> make publish

Optional configuration:

PYPI_TOKEN=<pypi-token> PYPI_ORG=<organization> PYPI_REPOSITORY=<index> make publish

Defaults:

• PYPI_ORG=comses
• PYPI_REPOSITORY=pypi

Create schema or data migrations

docker compose run --rm test /code/make_migrations.py -n <name-of-migration>

If you leave out the -n <name> the migration filename will be autogenerated.