Contributions

Thank you for your interest in contributing to vital_sqi! This guide provides a detailed workflow for setting up your development environment, contributing new features or fixes, and generating documentation.

Creating a Virtual Environment

A virtual environment helps to isolate dependencies for different projects, ensuring no conflicts arise between packages. Follow these steps:

Using `venv` (Python >= 3.3):

Install `venv`: .. code-block:: console

python -m pip install venv
Create a Virtual Environment: .. code-block:: console

python -m venv <environment-name>
Activate the Virtual Environment: .. code-block:: console

source <environment-name>/bin/activate # macOS/Linux <environment-name>Scriptsactivate # Windows

Using `virtualenv`:

Install `virtualenv`: .. code-block:: console

pip install virtualenv
Create a Virtual Environment: .. code-block:: console

virtualenv -p <python-path> <environment-name>
Activate the Virtual Environment: .. code-block:: console

source <environment-name>/bin/activate # macOS/Linux

To deactivate the environment, simply run:

deactivate

Note

For PyCharm users, you can configure virtual environments directly in the IDE. Students may qualify for a free license.

—

Forking the Repository

Navigate to the official repository: https://github.com/Oucru-Innovations/vital-sqi.
Click the Fork button (top-right corner).
This creates a copy of the repository under your GitHub account, including all branches, commits, and files.

—

Setting Up Your Fork Locally

Clone the Forked Repository: .. code-block:: console

git clone https://github.com/<your-username>/vital-sqi.git cd vital-sqi
Add the Upstream Remote: This ensures you can sync your fork with the original repository:
```
git remote add upstream https://github.com/Oucru-Innovations/vital-sqi.git
```
Verify Remotes: .. code-block:: console

git remote -v

Optional: Clone Specific Branches: If you only need certain branches, use:

git clone -b <branch-name> https://github.com/<your-username>/vital-sqi.git

—

Understanding the Repository Structure

After cloning the repository, you will see the following structure:

vital-sqi/
├── docs/                   # Documentation files
│   ├── build/              # Generated documentation (html)
│   ├── source/             # Sphinx source files
│       ├── conf.py         # Sphinx configuration
│       └── index.rst       # Documentation index
├── examples/               # Example scripts for users
├── src/                    # Source code for the library
│   ├── vital_sqi/          # Main package
│   │   ├── core/           # Core classes and algorithms
│   │   ├── tests/          # Unit tests
│   │   ├── utils/          # Utility functions
├── requirements.txt        # Project dependencies
├── setup.py                # Package installation script
└── Makefile                # Build automation script (e.g., for docs)

—

Installing the Package in Editable Mode

Editable mode allows you to test changes to the source code without reinstalling the package.

Install Dependencies: Navigate to the project root and run:
```
python -m pip install -r requirements.txt
```
Install the Package: .. code-block:: console

python -m pip install -e .[dev]

—

Generating Documentation

The documentation is built using Sphinx. Follow these steps:

Install Required Libraries: If not already installed:

python -m pip install sphinx sphinx-gallery sphinx-rtd-theme matplotlib

Generate HTML Documentation: Navigate to the docs folder and run:
```
make html
```
Preview Locally: Open docs/build/html/index.html in your browser.
Deploy to GitHub Pages: Use the pre-configured make github command:
```
make github
```

—

Running Tests

Tests ensure your changes work as expected and do not break existing functionality.

Install `pytest`: .. code-block:: console

python -m pip install pytest
Run Tests: .. code-block:: console

pytest

—

Submitting Contributions

Create a Feature Branch: Use a descriptive branch name:
```
git checkout -b feature/your-feature-name
```
Make Your Changes: Update the code, tests, and documentation as needed.
Run Tests and Build Documentation: Verify all tests pass and documentation builds without errors.
Commit and Push: .. code-block:: console

git add . git commit -m “Add feature: Description of your changes” git push origin feature/your-feature-name
Open a Pull Request: On GitHub, open a PR from your branch to the main branch of the official repository.

—

Helpful Tips

Style Guidelines: Follow PEP 8 for coding style.
Type Annotations: Use type hints for all functions.
Docstrings: Write docstrings in the NumPy format.
Testing: Write unit tests for any new functionality.
Documentation: Add or update relevant .rst files.

Happy coding and thank you for contributing to vital_sqi!