Set up initial Sphinx documentation and add Normalize filter docstrings

.gitignore

@@ -3,6 +3,11 @@ node_modules
 # Sphinx documentation
 docs/_build/
 
+# Pycache Untracked Files
+__pycache__/
+*.pyc
+
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

docs/conf.py

@@ -0,0 +1,19 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../src'))
+
+project = 'SCARR'
+author = 'decryptofy'
+release = '0.1'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,17 @@
+.. SCARR documentation master file
+
+Welcome to SCARR's documentation!
+=================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/modules.rst

@@ -0,0 +1,7 @@
+SCARR Modules
+=============
+
+.. automodule:: scarr.filters.normalize
+   :members:
+   :undoc-members:
+   :show-inheritance:

pyproject.toml

@@ -35,6 +35,9 @@ classifiers = [
 "Homepage" = "https://github.com/decryptofy/scarr"
 "Bug Tracker" = "https://github.com/decryptofy/scarr/issues"
 
+[project.optional-dependencies]
+dev = ["sphinx"]
+
 [tool.autopep8]
 ignore = "E501,W6"  # or ["E501", "W6"]
 in-place = true

src/scarr/filters/normalize.py

@@ -10,16 +10,53 @@
 from ..engines.stats import Stats
 
 class Normalize(Filter):
-    def __init__(self, stats:Stats) -> None:
+    """
+    A normalization filter that standardizes trace data using precomputed tile statistics.
+
+    This filter uses the mean and variance for a specific tile, obtained from the Stats object,
+    to normalize side-channel trace data to zero mean and unit variance.
+    """
+
+    def __init__(self, stats: Stats) -> None:
+        """
+        Initialize the Normalize filter with global tile statistics.
+
+        Parameters
+        ----------
+        stats : Stats
+            A Stats object that provides tile-level means, variances, and coordinate mappings.
+        """
         self.tile_means = stats.get_means()
         self.tile_variances = stats.get_variances()
         self.tiles = stats.get_tiles()
 
     def configure(self, tile_x, tile_y):
+        """
+        Select and configure the tile statistics for a specific (x, y) tile.
+
+        Parameters
+        ----------
+        tile_x : int
+            X-coordinate of the tile.
+        tile_y : int
+            Y-coordinate of the tile.
+        """
         tile_index = self.tiles.index((tile_x, tile_y))
-        self.mean = self.tile_means[tile_index,:]
-        self.variance = self.tile_variances[tile_index,:]
+        self.mean = self.tile_means[tile_index, :]
+        self.variance = self.tile_variances[tile_index, :]
+
+    def filter(self, traces: np.ndarray):
+        """
+        Apply normalization to a batch of traces using the configured tile statistics.
 
-    def filter(self, traces:np.ndarray):
+        Parameters
+        ----------
+        traces : np.ndarray
+            A NumPy array of raw side-channel traces to normalize.
 
-        return (traces - self.mean) / self.variance
+        Returns
+        -------
+        np.ndarray
+            Normalized traces with zero mean and unit variance.
+        """
+        return (traces - self.mean) / self.variance