Refactor workflows for dependency management and update documentation

.github/workflows/auto-format.yml

@@ -20,25 +20,22 @@ jobs:
 
     steps:
       - name: Checkout PR Branch
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           ref: ${{ github.head_ref }}
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           python-version: "3.10"
 
-      - name: Install black
-        run: pip install black
-
       - name: Get last commit message
         id: last_commit
         run: echo "message=$(git log -1 --pretty=%s)" >> $GITHUB_OUTPUT
 
       - name: Run black formatter
-        run: black minerva tests
+        run: uv run --frozen --extra dev black minerva tests
 
       - name: Check for changes
         id: changes

.github/workflows/continuous-testing.yml

@@ -30,35 +30,29 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
-      - name: Set up Python 3.10 with Caching
-        uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
           python-version: "3.10"
-          cache: "pip" # Cache pip packages to improve workflow runtime
+          enable-cache: true
 
       - name: Install Dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"  # Install dependencies from pyproject.toml (dev section)
+        run: uv sync --extra dev
 
       # ------- Black format check (minerva and tests directories) -------
-      - name: Install dependencies for black formatting check
-        run: |
-          pip install black nbqa
-
       - name: Check Python file formatting
         run: |
-          echo "🔍 Checking Python files..."
-          black --check --diff minerva tests || (
-            echo "❌ Black found formatting issues in Python files. Please reformat your files" && exit 1
+          echo "Checking Python files..."
+          uv run black --check --diff minerva tests || (
+            echo "Black found formatting issues in Python files. Please reformat your files" && exit 1
           )
 
       # ------- Run tests with coverage -------
       - name: Run Tests with Coverage
         run: |
-          pytest --cov=minerva --cov=tests --cov-report=term --cov-report=html
+          uv run pytest --cov=minerva --cov=tests --cov-report=term --cov-report=html
 
       - name: Upload HTML Coverage Report
         uses: actions/upload-artifact@v4
@@ -72,7 +66,7 @@ jobs:
           mkdir interrogate
 
       - name: Docstring Coverage
-        run: interrogate minerva -vv --fail-under=80 --generate-badge interrogate/interrogate_badge.svg --badge-format svg -o interrogate/simple-report.md
+        run: uv run interrogate minerva -vv --fail-under=80 --generate-badge interrogate/interrogate_badge.svg --badge-format svg -o interrogate/simple-report.md
         continue-on-error: true
 
       - name: Upload Docstring Coverage Report

.github/workflows/docs.yaml

@@ -8,24 +8,27 @@ jobs:
   docs:
     name: Minverva documentation
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
     steps:
 
     - name: Checkout Repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
-    - name: Set up Python 3.10 with Caching
-      uses: actions/setup-python@v5
+    - name: Install uv
+      uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
       with:
         python-version: "3.10"
-        cache: "pip"  # Cache pip packages to improve workflow runtime
 
-    - name: Install packages
+    - name: Install system dependencies
       run: |
         sudo apt-get update
         sudo apt-get install -y pandoc
-        python -m pip install --upgrade pip
-        pip install -e .[docs]  # Install dependencies from pyproject.toml (dev section)
-
+
+    - name: Install project with docs dependencies
+      run: uv sync --extra docs
+
     - name: Build docs
       run: |
         cd docs
@@ -35,7 +38,7 @@ jobs:
     # https://github.com/peaceiris/actions-gh-pages
     - name: Deploy
       if: success()
-      uses: peaceiris/actions-gh-pages@v3
+      uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
       with:
         publish_branch: gh-pages
         github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release_to_pypi.yml

@@ -5,31 +5,27 @@ on:
     types:
       - published
 
+permissions:
+  contents: read
+  id-token: write
+
 jobs:
   deploy:
     name: Build and Upload to PyPI
     runs-on: ubuntu-latest
+    environment: pypi
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
         with:
-          python-version: '3.10'
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install build twine
+          python-version: "3.10"
 
       - name: Build package
-        run: |
-          python -m build
+        run: uv build
 
       - name: Publish package to PyPI
-        env:
-          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN_MINERVA }}
-        run: |
-          python -m twine upload dist/* --username __token__ --password "$PYPI_API_TOKEN"
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

CONTRIBUTING.md

@@ -66,9 +66,9 @@ Every code contribution should be made through a pull request. This applies to a
 You code should follow the following guidelines:
 
 * **Documentation**: Make sure to document your code. This includes docstrings for functions and classes, as well as comments in the code when necessary. For the documentation, we use the numpydoc style. Also make sure to update the `README` file or other metadata files if necessary.
-* **Tests**: Make sure to write tests for your code. We use `pytest` for testing. You can run the tests with `python -m pytest` in the root directory of the project.
+* **Tests**: Make sure to write tests for your code. We use `pytest` for testing. Install dev dependencies with `uv sync --extra dev` (recommended) or `pip install -e ".[dev]"`, then run tests with `uv run pytest` or `pytest` respectively.
 * **Commit messages**: Make sure to write clear and concise commit messages. Include the issue number if you are fixing a bug.
-* **Dependencies**: Make sure to include any new dependencies in the `requirements.txt` and `pyproject.toml` file. If you are adding a new dependency, make sure to include a brief description of why it is needed.
+* **Dependencies**: Make sure to include any new dependencies in `pyproject.toml`. If you are adding a new dependency, make sure to include a brief description of why it is needed.
 * **Code formatting**: Make sure to run a code formatter on your code before submitting the PR. We use `black` for this.
 
 You should also try to avoid rewriting functionality, or adding dependencies for functionalities that are already present on one of our dependencies. This would make the codebase more bloated and harder to maintain.

README.md

@@ -32,11 +32,18 @@ Minerva offers a wide range of features to help you with your machine learning p
 
 ## Installation
 
-Minerva is currently under development and not yet available as a PyPI package. You can install it:
-- Locally, as any other Python package.
-- Using a Docker container, if you want to use the development environment.
+Minerva is available on [PyPI](https://pypi.org/project/minerva/). We recommend installing it with [uv](https://docs.astral.sh/uv/), a fast Python package and project manager, though pip works as well.
+
+### Install with uv (Recommended)
+
+If you don't have uv, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+uv pip install minerva
+```
+
+### Install with pip
 
-### Install With pip
 ```bash
 pip install minerva
 ```
@@ -47,15 +54,20 @@ pip install minerva
 
 ```bash
 git clone https://github.com/discovery-unicamp/Minerva.git
+cd Minerva
 ```
 
-2. And then navigate to the project directory and install the dependencies:
+2. Install dependencies — with uv (recommended):
 
 ```bash
-cd Minerva
-pip install .
+uv pip install .
 ```
 
+Or with pip:
+
+```bash
+pip install .
+```
 
 ### VSCode Development Environment using DevContainer
 
@@ -87,23 +99,43 @@ For more information on how to use Minerva, check the [documentation for example
 
 ## Testing
 
-To run the tests, you must install the development dependencies:
+First, install the development dependencies.
+
+With uv (recommended):
 
 ```bash
-pip install -e .[dev]
+uv sync --extra dev
+```
+
+With pip:
+
+```bash
+pip install -e ".[dev]"
 ```
 
 ### Unit Tests
 
-Then, you can run the tests using the following command:
+With uv:
+
+```bash
+uv run pytest tests/
+```
+
+With pip (after activating your environment):
 
 ```bash
 pytest tests/
 ```
 
 ### Coverage
 
-To generate a coverage report (in HTML), you can use the following command:
+With uv:
+
+```bash
+uv run pytest --cov=minerva --cov=tests --cov-report=term --cov-report=html
+```
+
+With pip:
 
 ```bash
 pytest --cov=minerva --cov=tests --cov-report=term --cov-report=html

docs/conf.py

@@ -41,7 +41,6 @@
     "myst_parser",  # MyST markdown parser
     "sphinx.ext.autodoc",  # Support for automatic documentation
     "autoapi.extension",  # Auto-generate API documentation
-    "sphinx_rtd_theme",  # ReadTheDocs theme
     "sphinx.ext.viewcode",  # Add "view source code" links
     "sphinx.ext.autodoc.typehints",  # Use type hints in autodoc
     "sphinx.ext.mathjax",  # Render math equations
@@ -62,11 +61,9 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
-htmlhelp_basename = "minerva_docs"
+html_theme = "furo"
 htmlhelp_basename = "minerva_docs"
 source_encoding = "utf-8"
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

docs/installation.md

@@ -1,37 +1,51 @@
 # Installation
 
-Minerva is currently under development but is already usable and have a development release available at [PyPI](https://pypi.org/project/minerva/). 
-You can install minerva for development or production use.
+Minerva is available at [PyPI](https://pypi.org/project/minerva/) for production use, and at [GitHub](https://github.com/discovery-unicamp/Minerva.git) for development.
 
-For production use, we recommend using the latest stable release available at [PyPI](https://pypi.org/project/minerva/).
-For development, you can use the latest development version available at [GitHub](https://github.com/discovery-unicamp/Minerva.git) using pip or by installing the VSCode DevContainer (recommended).
+We recommend using [uv](https://docs.astral.sh/uv/) for all installation workflows. uv is a fast Python package and project manager that handles virtual environments, dependency locking, and tool execution in one tool. pip works as a drop-in alternative everywhere uv is shown.
+
+If you don't have uv installed, follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
 ## Install via PyPI
 
-To install Minerva, you can use pip:
+**With uv (recommended):**
+
+```bash
+uv pip install minerva
+```
+
+**With pip:**
 
 ```bash
 pip install minerva
 ```
 
-This will install the latest version of Minerva and all its dependencies.
+Both commands install the latest version of Minerva and all its dependencies.
 
 
 ## Install Locally
 
-Installing Minerva in development mode allows you to work on the codebase and test changes without needing to reinstall the package every time you make a change. This is useful for contributors who want to develop and test Minerva. You can use pip or conda to install Minerva locally.
+Installing Minerva in development mode lets you work on the codebase and test changes without reinstalling after each edit. This is the recommended setup for contributors.
 
 1. Clone the repository:
 
 ```bash
 git clone https://github.com/discovery-unicamp/Minerva.git
+cd Minerva
 ```
 
-2. And then navigate to the project directory and install the dependencies:
+2. Install with development dependencies.
+
+**With uv (recommended)** — creates a virtual environment and installs everything from the lock file:
 
 ```bash
-cd Minerva
-pip install .
+uv sync --extra dev
+```
+
+**With pip:**
+
+```bash
+pip install -e ".[dev]"
 ```
 
 Or, you can create a conda environment and install Minerva in it:
@@ -88,13 +102,21 @@ git clone https://github.com/discovery-unicamp/Minerva.git
 
 ## Testing
 
-Once you have Minerva installed, you can use it as any other Python package using:
+Once you have Minerva installed, you can use it as any other Python package:
 
 ```python
 import minerva
 ```
 
-You also can run the unit tests using the following command:
+Run the unit tests with:
+
+**With uv:**
+
+```bash
+uv run pytest tests/
+```
+
+**With pip (after activating your environment):**
 
 ```bash
 pytest tests/

pyproject.toml

@@ -84,7 +84,7 @@ docs = [
     "sphinx-argparse",
     "sphinx-autoapi",
     "sphinx-autodoc-typehints",
-    "sphinx-rtd-theme",
+    "furo",
     "sphinx",
 ]
 analysis = ["codecarbon>=2.8.3", "ultralytics-thop>=2.0.14"]