Merge pull request #264 from flatironinstitute/sphinx

Sphinx

.gitignore

@@ -117,8 +117,8 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
+# sphinx build documentation
+/docs/_build
 
 # mypy
 .mypy_cache/
@@ -143,3 +143,14 @@ docs/generated/
 
 # nwb cahce
 nwb-cache/
+
+# scripting folder
+_scripts/
+
+# env variable for nwbs
+docs/data/
+
+# rst generated files
+docs/stubs
+
+

.readthedocs.yaml

@@ -14,13 +14,14 @@ build:
     pre_build:
       - gem install html-proofer -v ">= 5.0.9"  # Ensure version >= 5.0.9
     post_build:
-      # Check everything but the reference (because mkdocstrings do not set href=)
-      - htmlproofer $READTHEDOCS_OUTPUT/html  --checks Links,Scripts --ignore-urls "https://fonts.gstatic.com,https://www.jneurosci.org/content/25/47/11003" --assume-extension --check-external-hash --ignore-status-codes 403 --ignore-files "/.+\/html\/reference\/.+/"
-      # Check the reference allowing missing href
-      - htmlproofer $READTHEDOCS_OUTPUT/html/reference  --assume-extension --check-external-hash --ignore-urls "https://fonts.gstatic.com" --allow-missing-href --ignore-status-codes 403
-
-mkdocs:
-  configuration: mkdocs.yml
+      # Check everything except 403s and a jneurosci, which returns 404 but the link works when clicking.
+      - htmlproofer $READTHEDOCS_OUTPUT/html  --checks Links,Scripts,Images --ignore-urls "https://fonts.gstatic.com,https://celltypes.brain-map.org/experiment/electrophysiology/478498617,https://www.jneurosci.org/content/25/47/11003" --assume-extension --check-external-hash --ignore-status-codes 403 --ignore-files "/.+\/_static\/.+/","/.+\/stubs\/.+/","/.+\/tutorials/plot_02_head_direction.+/"
+      # The auto-generated animation doesn't have a alt or src/srcset; I am able to ignore missing alt, but I cannot work around a missing src/srcset
+      # therefore for this file I am not checking the figures.
+      - htmlproofer $READTHEDOCS_OUTPUT/html/tutorials/plot_02_head_direction.html  --checks Links,Scripts --ignore-urls "https://www.jneurosci.org/content/25/47/11003"
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
 
 # Optionally declare the Python requirements required to build your docs
 python:

docs/Makefile

@@ -0,0 +1,21 @@
+# 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     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+# Set an environ variable available during sphinx build
+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/_templates/autosummary/class.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+
+{% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: ./
+   {% for item in attributes %}
+      ~{{ objname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+{% endblock %}
+
+{% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: ./
+   {% for item in methods %}
+      ~{{ objname }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+{% endblock %}
+

docs/_templates/layout.html

@@ -0,0 +1,16 @@
+{% extends "!layout.html" %}
+
+{%- block footer %}
+<footer class="footer" style="border-top: 1px solid #ccc; padding-top: 10px">
+  <div class="container">
+    <div id="credits" style="width: 50%; float: left">
+      <p>
+      {% trans copyright=copyright|e %}&#169; Copyright {{ copyright }}, <a href="https://www.simonsfoundation.org/people/edoardo-balzani/">nemos authors</a>.{% endtrans %}<br/>
+      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> and the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/">PyData Theme</a>.<br/>
+      </p>
+    </div>
+    <div id="version" style="color: #999; float: right; margin: 15px">v{{ version }}</div>
+    </div>
+  </div>
+</footer>
+{%- endblock %}

docs/api_reference.rst

@@ -0,0 +1,137 @@
+.. _api_ref:
+
+API Reference
+=============
+
+.. _nemos_glm:
+The ``nemos.glm`` module
+------------------------
+Classes for creating Generalized Linear Models (GLMs) for both single neurons and neural populations.
+
+.. currentmodule:: nemos.glm
+
+.. autosummary::
+    :toctree: generated/glm
+    :recursive:
+    :nosignatures:
+
+    GLM
+    PopulationGLM
+
+.. _nemos_basis:
+The ``nemos.basis`` module
+--------------------------
+Provides basis function classes to construct and transform features for model inputs.
+
+.. currentmodule:: nemos.basis
+
+.. autosummary::
+    :toctree: generated/basis
+    :recursive:
+    :nosignatures:
+
+    Basis
+    SplineBasis
+    BSplineBasis
+    CyclicBSplineBasis
+    MSplineBasis
+    OrthExponentialBasis
+    RaisedCosineBasisLinear
+    RaisedCosineBasisLog
+    AdditiveBasis
+    MultiplicativeBasis
+    TransformerBasis
+
+.. _observation_models:
+The ``nemos.observation_models`` module
+--------------------------------------
+Statistical models to describe the distribution of neural responses or other predicted variables, given inputs.
+
+.. currentmodule:: nemos.observation_models
+
+.. autosummary::
+    :toctree: generated/observation_models
+    :recursive:
+    :nosignatures:
+
+    Observations
+    PoissonObservations
+    GammaObservations
+
+.. _regularizers:
+The ``nemos.regularizer`` module
+--------------------------------
+Implements various regularization techniques to constrain model parameters, which helps prevent overfitting.
+
+.. currentmodule:: nemos.regularizer
+
+.. autosummary::
+    :toctree: generated/regularizer
+    :recursive:
+    :nosignatures:
+
+    Regularizer
+    UnRegularized
+    Ridge
+    Lasso
+    GroupLasso
+
+The ``nemos.simulation`` module
+-------------------------------
+Utility functions for simulating spiking activity in recurrently connected neural populations.
+
+.. currentmodule:: nemos.simulation
+
+.. autosummary::
+    :toctree: generated/simulation
+    :recursive:
+    :nosignatures:
+
+    simulate_recurrent
+    difference_of_gammas
+    regress_filter
+
+
+The ``nemos.convolve`` module
+-----------------------------
+Utility functions for running convolution over the sample axis.
+
+.. currentmodule:: nemos.convolve
+
+.. autosummary::
+    :toctree: generated/regularizer
+    :recursive:
+    :nosignatures:
+
+    create_convolutional_predictor
+    tensor_convolve
+
+
+The ``nemos.identifiability_constraints`` module
+------------------------------------------------
+Functions to apply identifiability constraints to rank-deficient feature matrices, ensuring the uniqueness of model
+solutions.
+
+.. currentmodule:: nemos.identifiability_constraints
+
+.. autosummary::
+    :toctree: generated/identifiability_constraints
+    :recursive:
+    :nosignatures:
+
+    apply_identifiability_constraints
+    apply_identifiability_constraints_by_basis_component
+
+The ``nemos.pytrees.FeaturePytree`` class
+-----------------------------------------
+Class for storing the input arrays in a dictionary. Keys are usually variable names. 
+These objects can be provided as input to nemos GLM methods.
+
+.. currentmodule:: nemos.pytrees
+
+.. autosummary::
+    :toctree: generated/identifiability_constraints
+    :recursive:
+    :nosignatures:
+
+    FeaturePytree