Skip to content

Home

Jump to bottom
Amy Wooding edited this page Jul 16, 2026 · 8 revisions

Developer Guide

Welcome to the Toponymy developer documentation! This guide will help you set up your development environment, understand the project structure, run tests, and contribute effectively to the project.

Ways to Contribute

Contributions of all kinds are welcome. Here are some of the ways that you can contribute to Toponymy:

  1. File an issue. The easiest contribution to make is to [file an issue](https://github.com/TutteInstitute/toponymy/issues/new). Before filing an issue, please do a cursory search of [existing issues](https://github.com/TutteInstitute/toponymy/issues?utf8=%E2%9C%93&q=is%3Aissue). It also helps, but is not necessary, if you can provide clear instruction for how to reproduce a problem. If you have resolved an issue yourself please consider contributing the issue and solution so others can benefit from your work.
  2. Improve documentation. Contributing to documentation is the easiest way to get started with development. Anything that you as a new user found hard to understand, or difficult to work out, is an excellent place to begin.
  3. Submit a PR. Code contributions are always welcome, from simple bug fixes, to new features. The authors will endeavour to help walk you through any issues in the pull request discussion, so please feel free to open a pull request even if you are new to such things.
  4. Add an example. Example notebooks serve as both documentation and testable code. If you have a use case that you think would be helpful to others or would help to round out the test suite, please consider adding an example.

Development Setup

Prerequisites

Development Environment Setup

  1. Clone the repository
      git clone https://github.com/TutteInstitute/toponymy.git
      cd toponymy
  1. Install Python dependencies
      # Install the package in development mode
      uv sync --extra dev --extra example-notebooks

      # For documentation development (read the docs)
      uv sync --extra dev --extra example-notebooks --extra doc
  1. Install Ollama: See https://ollama.com/download. Needed for running the full test suite.

Project Structure

   toponymy/
   ├── toponymy/            # Main package source code
   │   ├── tests/              # Test suite
   │   ├── tools/              # Tools for helping to test and run docs notebooks
   │   ├── widgets/            # Widgets for plotting
   ├── examples/               # Example datasets
   ├── doc/                    # Documentation source files
   ├── .azure/templates        # CI configuration templates
   ├── azure-pipelines.yml     # CI configuration
   ├── README.md               # Project overview
   ├── LICENSE                 # License information
   ├── CODE_OF_CONDUCT.md      # Code of conduct for contributing
   └── pyproject.toml          # Project information

Development Workflow

Pull Request Process

  1. Fork the repository and create a branch
  2. Make your changes and commit them
  3. Run the tests locally and check the results
  4. Create a pull request and make sure CI tests pass
  5. Address any feedback from code reviewers
  6. Once approved, your changes will be merged

If you are fixing a known issue please add the issue number to the PR message. If you are fixing a new issue, feel free to file an issue and then reference it in the PR. You can [browse open issues](https://github.com/TutteInstitute/datamapplot/issues) to find something to work on.

Testing

Toponmy uses pytest. The tests live under toponymy/tests/. has several types of tests:

  1. Unit tests: Testing individual components. Runs on PRs.
  2. External tests: Tests API calls to some LLM providers. Runs on a nightly schedule
  3. Notebook Tests: Tests the read the docs notebooks run to completion. Runs Getting Started and changed notebooks on PR. Runs all docs notebooks on a weekly cadence.

Running the tests

Run all tests:

uv run pytest toponymy/tests -v

Run a specific test file:

uv run pytest toponymy/tests/test_toponymy.py -v

Run tests with coverage:

uv run pytest toponymy/tests --show-capture=no -v --disable-warnings \
--junitxml=junit/test-results.xml \
--cov=toponymy/ --cov-report=xml --cov-report=html

Continuous Integration

Toponymy uses [Azure Pipelines](https://dev.azure.com/TutteInstitute/build-pipelines/_build?definitionId=31) for continuous integration testing.

CI Configuration

The CI pipeline runs on:

  • Multiple Python versions (3.10, 3.11, 3.12)
  • Linux only right now

Finding Test Results in CI

  1. Go to the [Azure Pipelines](https://dev.azure.com/TutteInstitute/build-pipelines/_build?definitionId=31) for the repository
  2. Select the build you're interested in
  3. Navigate to the "Tests" tab to see test results

Handling CI Failures

If your pull request fails tests in CI:

  1. Click on the failing job to see detailed logs
  2. Make necessary changes to fix the failures
  3. Push your changes to update the pull request

Documentation

Contributing to documentation is the easiest way to get started. Providing simple clear or helpful documentation for new users is critical. Anything that you as a new user found hard to understand, or difficult to work out, are excellent places to begin. Contributions to more detailed and descriptive error messages is especially appreciated. To contribute to the documentation please use the above pull request process.

Toponymy uses Sphinx with Read the Docs for documentation. Documentation is written in either reStructuredText format (.rst) or in jupyter notebooks (.ipynb)and stored in the doc/ directory. Contributor docs are on this page (you found it!)

Building Documentation Locally

   # Install documentation dependencies
   uv sync --extra doc

   # Build HTML documentation
   cd doc
   make html

   # View the documentation (open _build/index.html in a browser)

Writing Good Documentation

  • Use clear, concise language
  • Include examples where appropriate
  • Explain the "why" not just the "how"
  • Keep API references up-to-date with code changes
  • Include diagrams or screenshots for complex features

Troubleshooting

Getting Help

Helpful Resources

Clone this wiki locally