Building from source

Building the crates

Rust 1.88 or newer is required.

git clone https://github.com/gtfierro/ontoenv-rs
cd ontoenv-rs

cargo build -p ontoenv-cli --release
./target/release/ontoenv --help

cargo test

The workspace holds four crates:

lib

ontoenv — the core environment, import resolution, and dependency graph.

cli

ontoenv-cli — the command-line front end.

python

The PyO3 bindings published to PyPI as ontoenv.

rdf5d

The on-disk RDF format used for graph storage and the metadata catalog.

Building the Python bindings

Python 3.11 or newer.

cd python
uv run maturin develop

uv run pytest

Building the docs

The documentation has its own pyproject.toml under docs/ so its tooling stays separate from the project’s.

./builddocs          # sync deps, build the extension, render HTML
./builddocs llms     # also render docs/_build/llms.txt for LLM ingestion

Or by hand:

cd docs
uv sync
uv run sphinx-build -M html . _build
open _build/html/index.html

How the docs are organized

The structure follows Diátaxis. When adding a page, put it in the section matching what the reader is doing:

tutorials/

Learning. A guaranteed-to-work path through a task, for someone who has not used OntoEnv before. No alternatives, no caveats, no edge cases.

how-to/

Working. One page per goal, assuming competence. Terse; link out for background rather than explaining inline.

reference/

Looking things up. Complete, dry, and organized by the shape of the API rather than by task. Tables over prose.

explanation/

Understanding. Why things are the way they are. This is where design rationale, trade-offs, and edge cases belong — keep them out of the other three.

The most common mistake is letting explanation leak into a how-to, or reference detail into a tutorial. If a paragraph starts with “note that” or “the reason for this is”, it probably belongs in explanation/.