Merge pull request #57 from pralab/documentation-and-tests

Add documentation, tests, and automatic tools

.github/workflows/lint.yml

@@ -0,0 +1,8 @@
+name: Ruff
+on: [push, pull_request]
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: chartboost/ruff-action@v1

.github/workflows/readthedocs-pr.yaml

@@ -0,0 +1,16 @@
+name: readthedocs/actions
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  pull-request-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "readthedocs-preview"

.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: Test and codecov report
+on: [push, pull_request]
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Install test requirements
+        run: pip install -r requirements-test.txt
+      - name: Run tests and collect coverage
+        run: pytest --cov src/
+      - name: Upload coverage reports to Codecov
+        uses: codecov/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: pralab/secml-torch

.gitignore

@@ -244,4 +244,7 @@ $RECYCLE.BIN/
 *.msp
 
 # Windows shortcuts
-*.lnk
+*.lnk
+
+# Example models and datasets
+examples/example_data/*

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+default_language_version:
+    python: python3.9
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+    -   id: check-added-large-files
+    -   id: check-toml
+    -   id: check-yaml
+        args:
+        -   --unsafe
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+-   repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.1.2
+    hooks:
+    -   id: ruff
+        args:
+        - --fix
+    -   id: ruff-format
+ci:
+    autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
+    autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate

.readthedocs.yaml

@@ -0,0 +1,28 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# SecMLT: Contribution Guide for Adversarial Machine Learning and Robustness Evaluation
+# SecMLT: Contribution Guide
 
-SecMLT is an open-source Python library for Adversarial Machine Learning and robustness evaluation. We welcome contributions from the research community to expand its capabilities, improve its functionality, or add new features. In this guide, we will discuss how to contribute to SecMLT through forks, pull requests, and code formatting using Black.
+SecMLT is an open-source Python library for Adversarial Machine Learning and robustness evaluation. We welcome contributions from the research community to expand its capabilities, improve its functionality, or add new features. In this guide, we will discuss how to contribute to SecMLT through forks, pull requests, and code formatting using Ruff.
 
 ## Prerequisites
 
@@ -39,10 +39,55 @@ copy of the SecMLT repository under your GitHub account.
 
 ## Formatting your code
 
-SecMLT uses Black for ensuring high-quality code formatting. Before submitting a pull request, make sure your code adheres to the SecMLT style guide by running the following command in the root directory:
-   ```bash
-   black .
-   ```
+In our project, we leverage [Ruff](https://docs.astral.sh/ruff/) and [pre-commit](https://pre-commit.com) to enhance code quality and streamline the development process.
+Ruff is a static code linter, while Pre-commit is a framework for defining pre-commit hooks.
+
+### Using Ruff
+
+Ruff is integrated into our project to perform code linting.
+It helps ensure adherence to coding standards, identifies potential bugs, and enhances overall code quality. Here's how to use Ruff:
+
+1. **Installation**: Make sure you have Ruff installed in your development environment. You can install it via pip:
+    ```
+    pip install ruff
+    ```
+
+2. **Running Ruff**: To analyze your codebase using Ruff, navigate to the project directory and run the following command:
+    ```
+    ruff check
+    ```
+    Ruff will analyze the codebase and provide feedback on potential issues and areas for improvement.
+
+### Using Pre-commit
+
+Pre-commit is employed to automate various tasks such as code formatting, linting, and ensuring code consistency across different environments. We use it to enforce Ruff formatting *before* commit.
+Here's how to utilize Pre-commit:
+
+1. **Installation**: Ensure that Pre-commit is installed in your environment. You can install it using pip:
+    ```
+    pip install pre-commit
+    ```
+
+2. **Configuration**: The project includes a `.pre-commit-config.yaml` file that specifies the hooks to be executed by Pre-commit. These hooks can include tasks such as code formatting, static analysis, and more.
+
+3. **Installation of Hooks**: Run the following command in the project directory to install the Pre-commit hooks:
+    ```
+    pre-commit install
+    ```
+    This command will set up the hooks specified in the configuration file to run automatically before each commit.
+
+4. **Running Pre-commit**: Whenever you make changes and attempt to commit them, Pre-commit will automatically execute the configured hooks. If any issues are found, Pre-commit will prevent the commit from proceeding and provide feedback on the detected issues.
+
+### Contributing with your Code
+
+When contributing code to the project, follow these guidelines to ensure a smooth and efficient contribution process:
+
+1. **Run Ruff and Pre-commit Locally**: Before making a pull request, run Ruff and Pre-commit locally to identify and fix potential issues in your code.
+
+2. **Address Ruff and Pre-commit Warnings**: If Ruff or Pre-commit identifies any issues, address them before submitting your code for review. This ensures that the codebase maintains high standards of quality and consistency.
+
+3. **Document Changes**: Clearly document any changes you make, including the rationale behind the changes and any potential impact on existing functionality.
+
 4. If there are no issues with your code, commit the changes using the `git add` command and push them to your forked repository:
    ```bash
    git add .
@@ -58,4 +103,4 @@ SecMLT uses Black for ensuring high-quality code formatting. Before submitting a
 4. Submit your pull request by clicking "Create pull request".
 5. The SecMLT maintainers will review your pull request, provide feedback, or merge it into the main repository as appropriate.
 
-We appreciate your contributions to SecMLT! If you have any questions or need assistance during the process, please don't hesitate to reach out to us on GitHub or other communication channels.
+We appreciate your contributions to SecMLT! If you have any questions or need assistance during the process, please don't hesitate to reach out to us on GitHub or other communication channels.

README.md

@@ -1,6 +1,11 @@
  # SecML-Torch: A Library for Robustness Evaluation of Deep Learning Models
 
-SecML-Torch (SecMLT) is an open-source Python library designed to facilitate research in the area of Adversarial Machine Learning (AML) and robustness evaluation. 
+ <a href="https://codecov.io/gh/pralab/secml-torch" >  <img src="https://codecov.io/gh/pralab/secml-torch/graph/badge.svg?token=7TM3NA0B5H"/>  </a>
+
+<a href='https://secml-torch.readthedocs.io/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/secml-torch/badge/?version=latest' alt='Documentation Status' /></a>
+
+
+SecML-Torch (SecMLT) is an open-source Python library designed to facilitate research in the area of Adversarial Machine Learning (AML) and robustness evaluation.
 The library provides a simple yet powerful interface for generating various types of adversarial examples, as well as tools for evaluating the robustness of machine learning models against such attacks.
 
 ## Installation
@@ -14,7 +19,7 @@ This will install the core version of SecMLT, including only the main functional
 
 ### Install with extras
 
-The library can be installed together with other plugins that enable further functionalities. 
+The library can be installed together with other plugins that enable further functionalities.
 
 * [Foolbox](https://github.com/bethgelab/foolbox), a Python toolbox to create adversarial examples.
 * [Tensorboard](https://www.tensorflow.org/tensorboard), a visualization toolkit for machine learning experimentation.
@@ -65,7 +70,5 @@ For more detailed usage instructions and examples, please refer to the [official
 
 ## Contributing
 
-We welcome contributions from the research community to expand the library's capabilities or add new features. 
+We welcome contributions from the research community to expand the library's capabilities or add new features.
 If you would like to contribute to SecMLT, please follow our [contribution guidelines](https://github.com/pralab/secml-torch/blob/main/CONTRIBUTING.md).
-
-

conftest.py

@@ -0,0 +1,5 @@
+"""Configuration for tests."""
+
+pytest_plugins = [
+    "secmlt.tests.fixtures",
+]

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,48 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import sys, os
+
+sys.path.insert(0, os.path.abspath("../src/secmlt"))
+
+project = "SecML-Torch"
+copyright = "2024, Maura Pintor, Luca Demetrio"
+author = "Maura Pintor, Luca Demetrio"
+release = "v0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.napoleon",
+]
+
+napoleon_google_docstring = False
+napoleon_use_param = False
+napoleon_use_ivar = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["*tests*"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+
+# -- Add readme and contribution guide -------------------------------------------------
+
+import pathlib
+
+for m in ["Readme.md", "CONTRIBUTING.md"]:
+    source_path = pathlib.Path(__file__).parent.resolve().parent.parent / m
+    target_path = pathlib.Path(__file__).parent / m.lower().replace(".md", ".rst")
+    from m2r import convert
+
+    with target_path.open("w") as outf:  # Change the title to "Readme"
+        outf.write(convert(source_path.read_text()))