Development guide¶

This tutorial walks you through setting up a working environment for developing pynxtools-raman itself.

Who is this tutorial for?¶

Anyone who wants to fix a bug, add a reader, or otherwise change the pynxtools-raman source code.

What should you know before this tutorial?¶

The guide on getting started with pynxtools.
The installation tutorial.

What will you know at the end of this tutorial?¶

How to set up your environment for developing pynxtools-raman.
How to run the tests and the linters.
How to build the documentation locally.
How to contribute your changes on GitHub.

Structure of the repository

The source code lives in src/pynxtools_raman, split into reader.py (the top-level reader dispatched by pynxtools), parsers/ (the parser classes and their shared base), rod_database/ (the pynx-raman CLI for downloading and batch-converting Raman Open Database records — not to be confused with parsers/rod.py, the single-file .rod parser), and config/ (the JSON mapping files). Unit tests live in tests, mirroring that structure. examples/ holds small example datasets used in the tutorials and in the tests.

Setup¶

It is recommended to use Python 3.12 with a dedicated virtual environment. Learn how to manage Python versions and virtual environments. We recommend uv; below you'll also find the equivalent venv/pip commands.

Start by creating a virtual environment:

uvvenv

uv venv --python 3.12

You need to have that Python version installed already.

python -m venv .venv

Development installation¶

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-username>/pynxtools-raman.git \
    --branch main \
    --recursive pynxtools-raman
cd pynxtools-raman

Install the package in editable mode, together with its development dependencies:

uvpip

uv pip install -e ".[dev]"

pip install --upgrade pip
pip install -e ".[dev]"

Linting and formatting¶

We use ruff and mypy for linting, formatting, and type checking. Install the pre-commit hook so both run automatically before every commit:

pre-commit install

Testing¶

Tests are written with pytest:

pytest -sv tests

Editing the documentation¶

Documentation is built with mkdocs and the Material for MkDocs theme. Install the extra dependencies for it:

uvpip

uv pip install -e ".[docs]"

pip install -e ".[docs]"

Then serve the docs locally, with live reload on save:

mkdocs serve

The config lives in mkdocs.yaml at the repository root; new pages need to be added to its nav section to show up in the sidebar.

Contributing on GitHub¶

Before making changes, pull the latest main into your fork and branch off it (or rebase), so your pull request doesn't drag in unrelated history:

git checkout main
git pull origin main
git checkout -b my-feature-branch

Once you're happy with your changes, commit them on that branch, push it to your fork, and open a pull request from there against FAIRmat-NFDI/pynxtools-raman's main branch. CI runs linting, the test suite, and a documentation build; once those pass and a review has happened, your change gets merged.

Developing `pynxtools-raman` as a NOMAD plugin¶

If you're working on the NOMAD integration (the Raman app or the metainfo schema), it's usually easiest to do that inside nomad-distro-dev, NOMAD's own development distribution — see the NOMAD documentation for how to set it up.

Troubleshooting¶

If you get stuck, open a GitHub issue.