Documentation update: add readthedocs with sphinx

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+      python: "3.8"
+  jobs:
+    post_install:
+      - sphinx-apidoc -M -o docs/generated sparsecoding
+      - pip install -r requirements.txt
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+      - requirements: docs/requirements.txt

README.md

@@ -1,25 +1,38 @@
-# Sparse Coding
-Reference sparse coding implementations for efficient learning and inference implemented in PyTorch with GPU support. 
+# RCTN SparseCoding Library
 
-## Dictionary Learning
-* Repo currently includes classic patch-wise sparse coding dictionary learning.
+[![Documentation status](https://readthedocs.org/projects/sparsecoding/badge/)](
+https://sparsecoding.readthedocs.io/)
 
-## Implemented Inference Methods
-* Locally Competative Algorithm (LCA)
-* Gradient Descent with Euler's method on Laplace Prior (Vanilla)
-* Laplacian Scale Mixture (LSM)
-* Iterative Shrinkage-threshold Algorithm (ISTA)
-* Generic PyTorch minimization of arbitrary loss function (PyTorchOptimizer)
+`sparsecoding` is a Python library developed by UC Berkeley's [Redwood Center for Theoretical Neuroscience (RCTN)](https://redwood.berkeley.edu). It provides efficient, batched, and GPU-compatible [PyTorch](https://github.com/pytorch/pytorch) implementations for sparse coding related-algorithms, including dictionary learning, inference, and data processing.
 
-# Setup
-1. Clone the repo.
-2. Navigate to the directory containing the repo directory.
-3. Run `pip install -e sparsecoding`
-4. Navigate into the repo and install the requirements using `pip install -r requirements.txt`
-5. Install the natural images dataset from this link: https://rctn.org/bruno/sparsenet/IMAGES.mat
-6. Try running the demo notebook: `examples/sparse_coding.ipynb`
+Historically, sparse coding has been largely focused on learning sparse representations of images and we provide visualization and transformation tools to work with such data. However, we’ve tried to structure the transformation, dictionary learning methods, and inference methods in a manner that is data-agnostic, making them applicable to a wide range of use cases.
+
+We believe that sharing code within the scientific community is an important part of science and we hope that the research community finds this library useful. 
+
+
+## Features
+
+- Check out our [Quickstart Guide](https://sparsecoding.readthedocs.io/en/latest/quickstart.html) for an overview and setup instructions.
+- Refer to the [API Reference](https://sparsecoding.readthedocs.io/en/latest/api.html) for detailed usage of the library's features.
+
+
+## Setup
+
+To install the library, follow these steps:
+
+```bash
+git clone https://github.com/rctn/sparsecoding.git
+cd sparsecoding
+pip install -e .
+pip install -r requirements.txt
+```
+
+For more detailed instructions, see our [Installation Guide](https://sparsecoding.readthedocs.io/en/latest/install.html).
+
+Note: If you're using a Jupyter notebook and make changes to the source files, you can either:
+* Restart the Jupyter kernel, or
+* Use the autoreload extension as explained [here](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html#autoreload).
 
-Note: If you are using a Jupyter notebook and change a source file, you can either: 1) restart the Jupyter kernel, or 2) follow instructions [here](https://ipython.readthedocs.io/en/stable/config/extensions/autoreload.html#autoreload).
 
 # Contributing
-See the [contributing](docs/contributing.md) document!
+We welcome contributions! Please see our [contributing](https://sparsecoding.readthedocs.io/en/latest/contributing.html) for details on how to get involved.

docs/api.rst

@@ -0,0 +1,67 @@
+=============
+API Reference
+=============
+
+.. py:currentmodule:: sparsecoding
+
+Dictionary learning models
+--------------------------
+
+.. automodule:: sparsecoding.models
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Inference methods
+-----------------
+
+.. automodule:: sparsecoding.inference
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Visualization tools
+-------------------
+
+.. automodule:: sparsecoding.visualization
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Priors
+------
+
+.. automodule:: sparsecoding.priors
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Datasets
+--------
+
+.. automodule:: sparsecoding.datasets
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Data transformations
+--------------------
+
+.. automodule:: sparsecoding.transforms.whiten
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Image transformations
+---------------------
+
+.. automodule:: sparsecoding.transforms.images
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/conf.py

@@ -0,0 +1,44 @@
+# 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 os
+
+project = 'RCTN sparsecoding'
+copyright = '2024, RCTN'
+author = 'RCTN'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+]
+
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+    'inherited-members': False,
+}
+
+exclude_patterns = [
+    '**/test_*',
+    '**/*_test.py',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

docs/contributing.rst

@@ -0,0 +1,63 @@
+============
+Contributing
+============
+
+We welcome all contributions to this project! Whether it’s reporting bugs, suggesting features, 
+fixing issues, or improving documentation, your input is invaluable.
+
+Bug Reporting
+-------------
+
+If you encounter a bug, please report it by creating an issue on GitHub. Include as much detail as 
+possible to help us reproduce and fix the issue.
+
+Adding Features or Fixing Bugs
+------------------------------
+
+If you’ve identified a new feature to add or a bug you can fix, follow these steps:
+
+#. Clone the ``main`` branch.
+#. Create a new branch to work on your changes. Use a descriptive name for your branch, such as 
+   ``fix-issue-123`` or ``feature-add-logging``.
+#. Use ``add``, ``commit``, and ``push`` to save your changes to the new branch.
+#. Create a pull request (PR). See the "Submitting a Pull Request" section for more details.
+
+Submitting a Pull Request
+-------------------------
+To ensure a smooth review process and maintain high code quality, follow these guidelines when 
+submitting a PR:
+
+#. If applicable, write unit tests for your changes. We use the 
+   `pytest <https://pytest.readthedocs.io/>`_ framework. Every Python module, extension module, 
+   or subpackage in the sparsecoding package directory should have a corresponding ``test_<name>.py`` 
+   file. Pytest examines these files for test methods (named ``test*``) and test classes (named 
+   ``Test*``). Add your tests to the appropriate ``test_*.py`` (create this file if it doesn't 
+   already exist).
+#. Verify that all tests pass by running ``pytest sparsecoding/`` from the base repository directory.
+#. Ensure your code adheres to the formatting guidelines specified in 
+   `PEP8 <https://peps.python.org/pep-0008/>`_ and validated by 
+   `flake8 <https://flake8.pycqa.org/en/latest/>`_.
+#. Prepare a detailed and clear PR description: 
+
+   * Summarize the purpose of the PR and the changes made.
+
+   * Include any relevant context, such as links to related issues or discussions.
+
+   * Specify testing steps or considerations for reviewers.
+
+#. Submit your PR and assign reviewers as necessary.
+#. Reviewers: Use squash and merge when merging the PR.
+
+   * Set the merge description to match the PR description.
+
+   * Squash commits into a single commit to maintain a clean project history.
+
+
+Coding Style Guidelines
+-----------------------
+
+We follow the `NumPy documentation standards <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
+
+1. Format your code according to the `flake8 <https://flake8.pycqa.org/en/latest/>`_ standard.
+2. Use underscores to separate words in non-class names (e.g., ``n_samples`` instead of ``nsamples``).
+3. Avoid single-character variable names.

docs/index.rst

@@ -0,0 +1,35 @@
+.. sparsecoding documentation master file, created by
+   sphinx-quickstart on Fri Nov 15 13:23:58 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+#######################################
+RCTN sparsecoding library documentation
+#######################################
+
+`sparsecoding`_ is a python library developed by the `Redwood Center for 
+Theoretical Neuroscience (RCTN) <https://redwood.berkeley.edu>`_ which contains 
+performant `pytorch <https://github.com/pytorch/pytorch>`_ implementations of sparse coding dictionary learning, 
+inference, and data processing. It was written to be a useful research tool 
+for applying various sparse coding methods to data. 
+
+We believe that sharing code within the scientific community is an important 
+part of science and we hope that the research community finds this library 
+useful. 
+
+.. _sparsecoding: https://github.com/rctn/sparsecoding/
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   install
+   quickstart
+   api
+   contributing
+
+
+License
+-------
+
+`sparsecoding`_ has a BSD-3-clause license, as found in the `LICENSE <https://github.com/rctn/sparsecoding/blob/main/LICENSE>`_ file.

docs/install.rst

@@ -0,0 +1,20 @@
+============
+Installation
+============
+
+The quickest way to install the library is by cloning it directly from GitHub:
+
+.. code:: bash
+
+    git clone https://github.com/rctn/sparsecoding.git
+    cd sparsecoding
+    pip install -e sparsecoding
+    pip install -r requirements.txt
+
+The last command installs the dependencies required for the RCTN sparse coding library, including:
+
+- ``numpy``
+- ``scipy``
+- ``matplotlib``
+- ``torch``
+- ``torchvision``