Home

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. Please do a quick search of existing issues first, and include steps to reproduce if you can.
2. Improve documentation. Anything you found hard to understand as a new user is an excellent place to start. See Writing Documentation.
3. Submit a PR. Bug fixes and new features are always welcome — see Contributing a Pull Request for the process. Don't hesitate to open a PR even if you're new to this; reviewers will help.
4. Add an example. Example notebooks serve as both documentation and testable code.

Getting Started

New to the project? Start here:

• Setting Up Your Development Environment — clone the repo, install dependencies
• Contributing a Pull Request — the PR process, from branch to merge.
• Writing Documentation — building the docs locally and what goes into writing documentation.
• Toponymy Architecture — give the internal architecture documentation a quick read

Testing and Debugging

• Running the Test Suite — how to run unit, external, and notebook tests locally.
• Adding Documentation Notebooks to Tests — how notebook examples get tested in CI, and how to add your own.
• Running Connection Tests maybe belongs in Read the Docs
• Using Callback Hooks for Debugging LLM calls maybe belongs in Read the Docs

Reference

• CI Configuration — what runs where, and on what schedule.
• Notebook Testing Reference — config options, environment variables, CLI flags.

Troubleshooting & Getting Help

• Open an issue on GitHub
• Ask questions in Discussions
• Check the user documentation

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

Helpful Resources

• NumPy Docstring Guide
• Sphinx Documentation
• Azure Pipelines Documentation