Contributing¶

Thank you for your interest in contributing to pypsa2smspp! This guide covers how to contribute to the codebase as well as to the documentation.

Contributing to the Code¶

Setup¶

Clone the repository:

git clone https://github.com/SPSUnipi/pypsa2smspp
cd pypsa2smspp

Create a virtual environment (using venv or conda):

# Using venv
python -m venv .venv
source .venv/bin/activate

# Or using conda
conda create -n pypsa2smspp python=3.12
conda activate pypsa2smspp

Install the package in editable mode with development dependencies and pre-commit hooks:
```
pip install -e ".[dev]"
pre-commit install
```

Running Tests¶

Run the test suite with:

pytest

Code Style¶

Code style is enforced automatically by ruff via pre-commit hooks. To run the hooks manually:

pre-commit run --all-files

Submitting Changes¶

Create a new branch for your feature or fix.
Make your changes and add tests if applicable.
Ensure the tests and pre-commit hooks pass.
Open a pull request describing your changes.

Contributing to the Documentation¶

Setup¶

Install the documentation dependencies:

pip install -e ".[dev,docs]"

Building Documentation Locally¶

To preview the documentation locally:

mkdocs serve

Then open your browser at http://127.0.0.1:8000.

To build the static site:

mkdocs build

Adding New Pages¶

Create a new Markdown file in the appropriate docs/ subdirectory.
Add the page to the nav section of mkdocs.yml.

Writing Docstrings¶

Python docstrings are automatically included in the API reference using mkdocstrings. Follow the NumPy docstring format. Example:

def my_function(param1: int, param2: str) -> bool:
    """Short description of the function.

    Parameters
    ----------
    param1 : int
        Description of param1.
    param2 : str
        Description of param2.

    Returns
    -------
    bool
        Description of the return value.
    """

Adding Notebooks¶

Place Jupyter notebooks in docs/examples/ and add them to the nav section in mkdocs.yml under Examples.