Contributing#
SplineOps welcomes reproducible bug reports, numerical improvements, examples, and documentation fixes. For a numerical issue, include a small input, the call, the expected result, and your SplineOps, NumPy, SciPy, and Python versions.
Development setup#
Clone the repository and run the following commands from its root. Use a supported Python version, currently 3.11 through 3.13. Building an editable installation also requires a C++17 compiler; on Windows, use Visual Studio Build Tools with the C++ workload.
Create an environment with either standard Python or uv:
python -m venv .venv
Or, with uv:
uv venv --python 3.12 .venv
Activate the environment on Linux or macOS:
source .venv/bin/activate
On Windows PowerShell:
.\.venv\Scripts\Activate.ps1
Install the development dependencies using the installer you chose:
python -m pip install -e ".[dev]"
Or, with uv:
uv pip install -e ".[dev]"
Both workflows use the same dependencies and build configuration in
pyproject.toml. Mamba is not required. uv is optional; CI continues to use pip
and tox. See the uv environment guide
for selecting an interpreter without activating an environment.
Checks before a pull request#
Run the tests relevant to your change, then the formatting and type checks:
python -m pytest -q
python -m tox -e format-check,type
For numerical fixes, add a regression based on an independent formula, reference implementation, or invariant. Exercise the affected precisions, boundaries, and shapes. Check accuracy before comparing performance, and record the workload and environment alongside timing results.
Public behavior must follow the API stability policy. Document intentional numerical corrections in the changelog. Keep changes focused so a reviewer can connect the reported problem, implementation, and validation.
Docstring standard#
Use the NumPy docstring format for public modules, classes, functions, and methods. Sphinx renders this format through its Napoleon extension.
Start with a short summary, then use Parameters, Returns or Yields,
Raises, Notes, References, and Examples where applicable. Omit sections
that add no information. Use Examples, not Example, as the section heading.
Type annotations describe Python types; docstrings must also explain array shapes, precision rules, coordinate units, boundaries, and whether inputs can be modified or outputs can share memory. Describe actual behavior rather than inferring these contracts from annotations. Keep examples small, deterministic, and based on public imports. Prefer lines around 75 characters for prose.
This illustrative evaluation-method docstring shows the format. Adapt its contract and example to the method being documented:
"""Evaluate a one-dimensional spline at query coordinates.
Parameters
----------
coordinates : ndarray of shape (n_points,)
Finite query coordinates in the construction grid's physical units.
Returns
-------
values : ndarray of shape (n_points,)
Interpolated values. The input coordinates are not modified.
Raises
------
ValueError
If a query coordinate is not finite.
Examples
--------
>>> import numpy as np
>>> from splineops import TensorSpline
>>> spline = TensorSpline(
... np.array([0.0, 2.0, 4.0]), np.arange(3.0),
... bases="linear", modes="mirror",
... )
>>> spline(np.array([0.5, 1.5]))
array([1., 3.])
"""
Documentation and examples#
Install the documentation dependencies with your chosen installer:
python -m pip install -e ".[docs]"
Or:
uv pip install -e ".[docs]"
Build the documentation, execute the gallery, and validate sharing metadata:
python -m sphinx -b html docs docs/_build/html -W --keep-going
python scripts/check_docs_social_metadata.py docs/_build/html
Open docs/_build/html/index.html to inspect the result. For gallery or layout
changes, check the affected pages in both themes and at a narrow width. A
parse-only build does not validate executed examples or their thumbnails.
Gallery pages provide downloadable source files and notebooks for local use. JupyterLite execution in the browser is not supported. The documentation does not enable a JupyterLite extension or advertise a launch button. Adding it would require a separately validated browser environment and compatible native dependencies; ordinary local notebooks do not depend on JupyterLite.
See release validation for the complete platform, wheel, stability, and publication checks.