Documentation update: add readthedocs with sphinx

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+      python: "3.7"
+  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.patch
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/conf.py

@@ -0,0 +1,33 @@
+# 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',
+]
+
+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_static_path = ['_static']
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

docs/contributing.rst

@@ -0,0 +1,41 @@
+============
+Contributing
+============
+
+We welcome all contributions!
+
+Bug Reporting
+-------------
+
+If you encounter a bug, please report it by creating an issue on GitHub.
+
+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 ``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
+-------------------------
+
+#. If applicable, write unit tests for your changes and add them to the 
+   `tests directory <https://github.com/rctn/sparsecoding/blob/main/tests>`_.
+#. Verify that all tests pass by running ``python -m unittest discover tests -vvv``.
+#. 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/>`_.
+#. Provide a concise and descriptive title for your PR that summarizes the changes made in your branch.
+#. Submit your PR and assign reviewers as necessary.
+
+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``

docs/quickstart.rst

@@ -0,0 +1,40 @@
+==========
+Quickstart
+==========
+
+Overview
+--------
+
+.. _sparsecoding: https://github.com/rctn/sparsecoding/
+
+`sparsecoding`_ is a Python package that provides tools for implementing sparse coding algorithms. 
+Traditionally, sparse coding has been primarily used for learning sparse representations of images. 
+To support this, we include tools for visualization and data transformation specific to image data. 
+However, we have designed the dictionary learning and inference methods to be data-agnostic, 
+allowing for broader applications.
+
+The `sparsecoding`_ library is built largely on PyTorch, enabling it to inherit several 
+performance benefits, such as:
+
+- GPU support
+- Batched operations
+- Auto-grad optimizers
+
+Structure of the Library
+-------------------------
+
+The functionalities of `sparsecoding`_ are organized into several modules:
+
+- ``sparsecoding.models``: Contains dictionary learning models (e.g., SparseCoding).
+- ``sparsecoding.inference``: Includes algorithms for computing latent coefficients.
+- ``sparsecoding.visualization``: Provides tools for visualizing image dictionaries and data.
+- ``sparsecoding.priors``: Offers methods for sampling from various sparse coding priors.
+- ``sparsecoding.datasets``: Contains utilities for loading datasets.
+- ``sparsecoding.transforms``: Includes methods for working with data, such as whitening and 
+  extracting patches from images.
+
+Getting Started
+---------------
+
+Explore our `example notebooks <https://github.com/rctn/sparsecoding/tree/main/examples>`_ 
+to get started.

docs/requirements.txt

@@ -0,0 +1,3 @@
+.
+sphinx
+sphinx-rtd-theme