Contribute¶
Contributions are much welcome for the documentation and for defects. Defects means here both behavior not conforming the specification and missing but desirable features. The following two sections describes the process that I use for code development and documentation writing.
Contribution for the Python Package¶
The code and development happens in this GitHub repository.
For contributions, use the following guidelines:
-
Fork the project on GitHub, clone the fork to your Operating System and open the repository as folder/workspace in your favorite IDE. I use VSCode + Python extension.
-
Any change applied to the source code should be tested against the multiple tests included within the repository.
-
Once satisfied, push your changes as a new branch to your fork and create a Pull Request to the original repository.
-
A Pull Request triggers the Continuous Integration tests on the main GitHub repository and only after passing these tests a PR can be merged into main by the maintainer.
Note to self
From a clone of the repository, an environment with uv including the optional dependencies and the test tools:
uv venv --python 3.13
uv pip install -e ".[dev]" pytest
uv run pytest tests
The code is linted and formatted with ruff, as configured in pyproject.toml; CI checks both:
uvx ruff check
uvx ruff format
The public API (Topology) is typed, and CI checks the types with mypy, also from the side of a user (tests/typing_api.py):
uv run --with mypy mypy topojson tests/typing_api.py
Or install the package including optional dependencies directly from the GitHub repository using:
pip install "topojson[dev] @ git+https://github.com/mattijn/topojson.git"
Or partly using conda:
conda create -n topo_dev
conda activate topo_dev
conda install flit codecov pytest ruff
conda install numpy shapely geojson pyshp fiona geopandas altair ipywidgets
pip install simplification
Contribution for the Documentation¶
The documentation is built with Zensical from the Markdown in the docs folder, as configured in zensical.toml, and published to GitHub Pages by the workflow docs. To build it locally, install the documentation tools (next to the optional dependencies, which the examples use) and serve it from the root of the repository:
uv pip install -e ".[dev,docs]"
zensical serve
The server address is shown in the terminal, and a change in the Markdown is shown directly.
The examples on the example pages and How it works run while the site is built (markdown-exec), so the output below them is that of the current code. Examples that write or read files, or draw in a notebook, are shown and not run.
The API reference is created from the docstrings and type annotations in the code by mkdocstrings: a page such as docs/api/topojson.core.topology.md holds only topojson.core.topology.
The charts on the example pages are Vega-Lite specifications in docs/json. They are created by running the examples of these pages; to update them, run from the root of the repository:
python generate/make-docs-charts.py
The lens on the overview page draws the arcs of Africa with the weight of each vertex, from docs/json/lens_africa.json; to update it:
python generate/make-docs-lens.py
The figures of the steps on the page How it works draw what each step gives for the toy example, from docs/json/steps.json; to update it:
python generate/make-docs-steps.py
The other figures drawn this way, on the pages Example usage, Types of input data, Settings and tuning, Retrieval data types, Incremental updates and Quantization, come from docs/json/fig_*.json; to update them:
python generate/make-docs-figures.py