Initial sphinx docs (#500)

* Initial sphinx docs

* Update rye

* Rye fmt

* Update uv lock

* Add Github action

* Update documentation.yml

---------

Co-authored-by: Andrew Ramirez <[email protected]>
Co-authored-by: Aaron Meyer <[email protected]>

Author: 3 people

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+    contents: write
+
+jobs:
+    docs:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+            - uses: actions/setup-python@v5
+            - name: Install uv
+              uses: astral-sh/setup-uv@v6
+            - name: Sphinx build
+              run: |
+                  uv run sphinx-build docs docs/_build
+            - name: Deploy to GitHub Pages
+              uses: peaceiris/actions-gh-pages@v4
+              if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+              with:
+                  publish_branch: gh-pages
+                  github_token: ${{ secrets.GITHUB_TOKEN }}
+                  publish_dir: docs/_build
+                  force_orphan: true

.gitignore

@@ -6,27 +6,6 @@ __pycache__/
 # C extensions
 *.so
 
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-pip-wheel-metadata/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -51,23 +30,6 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
 # Sphinx documentation
 docs/_build/
 

RISE/figures/figure2b_e.py

@@ -33,4 +33,5 @@ def makeFigure():
 
     plot_labels_pacmap(X, "Cell Type", ax[3])
 
+
     return f

docs/api.rst

@@ -0,0 +1,28 @@
+API Reference
+=============
+
+.. automodule:: RISE
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: RISE.factorization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: RISE.imports
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: RISE.logisticReg
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: RISE.gating
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/conf.py

@@ -0,0 +1,72 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+import sys
+from pathlib import Path
+
+# Add the parent directory to the path so we can import RISE
+# This allows Sphinx to find the RISE package
+project_root = Path(__file__).parent.parent.resolve()
+sys.path.insert(0, str(project_root))
+
+# Project information
+project = "RISE"
+copyright = "2024, Andrew Ramirez, Aaron Meyer"
+author = "Andrew Ramirez, Aaron Meyer"
+
+# General configuration
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Napoleon settings for NumPy-style docstrings
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_attr_annotations = True
+
+# Autodoc configuration
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+    "show-inheritance": True,
+    "inherited-members": False,
+}
+
+# Intersphinx mapping for external documentation
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "tensorly": ("http://tensorly.org/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+}
+
+# Options for HTML output
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "includehidden": True,
+    "titles_only": False,
+}

docs/index.rst

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

pyproject.toml

@@ -46,6 +46,8 @@ dev = [
     "scanorama>=1.7.4",
     "harmonypy>=0.0.10",
     "scib>=1.1.5",
+    "sphinx>=7.0,<9.0",
+    "sphinx-rtd-theme>=3.0.0",
     "ruff>=0.14.7",
 ]