Contributing to kfactory

kfactory is an open-source project — contributions are welcome!

Quick links

• GitHub repository
• Issue tracker
• Pull request template

Development setup

kfactory uses uv for environment management and just as a task runner.

# Clone the repository
git clone https://github.com/gdsfactory/kfactory.git
cd kfactory

# Set up the full development environment (installs all extras + pre-commit hooks)
just dev

just dev is equivalent to:

uv sync --all-extras
uv pip install -e . -U
uv run pre-commit install

Running tests

# Full test suite (parallel, uses logical CPU count)
just test

# Minimum-dependency variant (checks nothing was accidentally removed)
just test-min

# With coverage report in the terminal
just dev-cov

# Single test file or test by name
uv run -p 3.14 --with . --extra ci --isolated pytest tests/test_kcell.py -s

Tests require the git submodules to be initialised (just init-submodule is run automatically before just test).

Building the docs

The docs build uses zensical, the successor to mkdocs by the Material for MkDocs team.

# Build once (outputs to docs/site/)
just docs

# Live-reload server (edit files, browser refreshes automatically)
just docs-serve

# Remove the build artefact
just docs-clean

The build runs in two stages:

1. Pre-build (docs-build-source): docs/scripts/build_docs_source.py converts every jupytext .py notebook under docs/source/ to executed .md + a downloadable .ipynb, and writes mkdocstrings stub pages under docs/source-built/reference/. Outputs go to docs/source-built/ (gitignored). Runs are cached by content hash in docs/.build-cache/ — only changed notebooks re-execute.
2. Render: zensical reads docs/source-built/ and produces the final HTML in docs/site/.

Any exception in a notebook stops the build. Always run just docs locally before opening a docs PR.

When writing a new doc page, follow the jupytext percent format used throughout the repo — see docs_overhaul/notes_build_system.md in the repository for templates and gotchas. Each rendered notebook page also gets a "Download notebook (.ipynb)" button at the top so readers can re-execute locally.

Code quality

# Lint
just lint        # ruff check

# Format
just format      # ruff format

# Type check (daemon — fast on repeat runs)
just mypy

# Experimental faster type checker
just ty

Pre-commit runs ruff check --fix and ruff format automatically on every git commit once just dev has been run.

Contribution workflow

1. Fork the repository and create a feature branch from main.
2. Make your changes. Add or update tests in tests/ if touching library code.
3. Run just test and just docs (if you touched documentation).
4. Open a pull request against main with a short summary of what and why.

PR guidelines

• Keep PRs focused — one logical change per PR is easier to review.
• Add a test for every new public function or behaviour change.
• Documentation notebooks are required for new features exposed to end users.
• The PR title is used by the release drafter; start it with a verb (Add, Fix, Update, Remove).

Project layout

src/kfactory/          # library source
tests/                 # pytest tests
docs/
  source/              # documentation pages (Markdown + jupytext .py notebooks)
  source-built/        # pre-build output (gitignored — created by docs-build-source)
  scripts/             # build_docs_source.py (notebook → .md + .ipynb pipeline)
  zensical.yml         # navigation + plugin config
Justfile               # common dev commands
pyproject.toml         # package metadata + dependencies

Dependency extras

Getting help

• Open a GitHub issue for bugs or feature requests.
• For usage questions, the How-To Guides and FAQ are a good starting point.

See Also