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,31 +1,37 @@
-# Sparse Coding
+# RCTN SparseCoding Library
 
-Reference sparse coding implementations for efficient learning and inference implemented in PyTorch with GPU support.
+[![Documentation status](https://readthedocs.org/projects/sparsecoding/badge/)](
+https://sparsecoding.readthedocs.io/)
 
-## Features
+`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.
+
+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 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.
 
-### Dictionary Learning
 
-* Repo currently includes classic patch-wise sparse coding dictionary learning.
+## Features
 
-### Implemented Inference Methods
+- 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.
 
-* 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)
 
 ## Setup
 
-1. Clone the repo.
-2. Navigate to the directory containing the repo directory.
-3. Run `pip install -e ".[all]"`
-4. Install the natural images dataset from this link: https://rctn.org/bruno/sparsenet/IMAGES.mat
-5. Try running the demo notebook: `examples/sparse_coding.ipynb`
+To install the library, follow these steps:
+
+```bash
+git clone https://github.com/rctn/sparsecoding.git
+cd sparsecoding
+pip install -e ".[all]"
+```
+
+Try running the demo notebook: `examples/sparse_coding.ipynb`.
+
+For more detailed instructions, see our [Installation Guide](https://sparsecoding.readthedocs.io/en/latest/install.html).
 
-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).
+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).
 
-## Contributing
 
-See the [contributing](docs/contributing.md) document!
+# Contributing
+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,19 @@
+============
+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 ".[all]"
+
+The last command installs the dependencies required for the RCTN sparse coding library, including:
+
+- ``numpy``
+- ``scipy``
+- ``matplotlib``
+- ``torch``
+- ``torchvision``