Prerequisites and Notes regarding the Development Guide¶

Getting Started¶

This package uses the Python project manager uv. To start development, please follow these steps:

Please refer to installation instructions for uv. Please use version 0.3.0 or higher.

Clone this repository:.

git clone https://github.com/IMMS-Ilmenau/netlist-carpentry.git
cd netlist-carpentry

Use uv sync to generate a virtual environment in .venv. This virtual environment can be sourced as usual:
```
uv sync
source .venv/bin/activate
```

The virtual environment will contain the package in editable mode, as well as all development dependencies. VS Code can use it too!

To install packages use uv pip install <package-name>. Please note that you should never install any packages to the .venv manually! If you need additional dependencies or development dependencies, you can also edit them accordingly in pyproject.toml and re-run uv sync.

Running Tests¶

This project uses tox for test orchestration.

By running it, you will run pytest, mypy and ruff all in one command:

uv run tox

(mypy is currently deactivated, because of... reasons)

uv will automatically download Python versions for tox.

Of course, you can run the tools independently too (as usual). After activating the .venv, you can call them as usual, for example:

source .venv/bin/activate
ruff check src/netlist_carpentry
mypy -p netlist_carpentry
pytest netlist_carpentry

Commiting changes¶

Before committing any changes, please remember the following steps:

Run all tests and static code checks via tox:
```
uv run tox
```
(Optional) If you changed any dependencies (or just to be sure!), please run uv sync to re-create the lock file for your project. It must be committed to version control. The lock file allows restoring the exact environment you used yourself during development!
(Optional) If you edited the documentation, please try building it in --strict mode. This will turn warnings to errors. The same will happen in Gitlab CI.
```
uv run mkdocs build --strict
```

Building the documentation¶

The documentation for this project is built with MkDocs, the Material theme and mkdocstrings.

After installing the development requirements, you can build the documentation locally with:

uv run mkdocs build

The results will be in docs/site.

You can also serve a preview of the documentation:

uv run mkdocs serve

The website will live update to changes in source code, both inside 'docs/src' and the Python source code src/netlist_carpentry.