docs: build using sphinx

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][],
+and this project adheres to [Semantic Versioning][].
+
+[keep a changelog]: https://keepachangelog.com/en/1.0.0/
+[semantic versioning]: https://semver.org/spec/v2.0.0.html
+
+## [Unreleased]
+
+### Added
+
+-   Basic tool, preprocessing and plotting functions

README.md

@@ -1,10 +1,10 @@
 # scanvi-explainer
 
-[![build](https://github.com/brickmanlab/scanvi-explainer/actions/workflows/build.yml/badge.svg)](https://github.com/brickmanlab/scanvi-explainer/actions/workflows/build.yml)
+[![build][build-badge]][build-link]
 
 Interpretability extension for [scANVI] using [SHAP] package.
 
-Please see our [example](Example.ipynb) notebook on how to run scANVI Explainer.
+Please see our [example](docs/notebooks/Example.ipynb) notebook on how to run scANVI Explainer.
 
 ## Installation
 
@@ -19,16 +19,13 @@ $ git clone https://github.com/brickmanlab/scanvi-explainer.git && cd scanvi-exp
 $ uv sync
 ```
 
-[scANVI]: https://docs.scvi-tools.org/en/stable/api/reference/scvi.model.SCANVI.html#scvi.model.SCANVI
-[SHAP]: https://github.com/shap/shap
-
 ## Citation
 
 Please consider citing scANVI Explainer if you use in your research.
 
 > Deep Learning Based Models for Preimplantation Mouse and Human Development <br>
 > Martin Proks, Nazmus Salehin, Joshua M. Brickman <br>
-> bioRxiv 2024.02.16.580649; doi: [10.1101/2024.02.16.580649](https://doi.org/10.1101/2024.02.16.580649)
+> bioRxiv 2024.02.16.580649; doi: [10.1101/2024.02.16.580649]
 
 ```BibTeX
 @article{Proks2024.02.16.580649,
@@ -43,3 +40,9 @@ Please consider citing scANVI Explainer if you use in your research.
 	journal = {bioRxiv}
 }
 ```
+
+[build-badge]: https://github.com/brickmanlab/scanvi-explainer/actions/workflows/build.yml/badge.svg
+[build-link]: https://github.com/brickmanlab/scanvi-explainer/actions/workflows/build.yml
+[scANVI]: https://docs.scvi-tools.org/en/stable/api/reference/scvi.model.SCANVI.html#scvi.model.SCANVI
+[SHAP]: https://github.com/shap/shap
+[10.1101/2024.02.16.580649]: https://doi.org/10.1101/2024.02.16.580649

docs/Makefile

@@ -0,0 +1,20 @@
+# 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".
+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/api.md

@@ -0,0 +1,15 @@
+# API
+
+## SCANVIDeep
+
+```{eval-rst}
+.. currentmodule:: scanvi_explainer
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+
+    scanvi_deep
+```

docs/changelog.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

docs/conf.py

@@ -0,0 +1,123 @@
+# Configuration file for the Sphinx documentation builder.
+
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+import sys
+from datetime import datetime
+from importlib.metadata import metadata
+from pathlib import Path
+
+# -- Project information -----------------------------------------------------
+
+# NOTE: If you installed your project in editable mode, this might be stale.
+#       If this is the case, reinstall it to refresh the metadata
+info = metadata("scanvi-explainer")
+project_name = info["Name"]
+
+author = ", ".join([x.split("<")[0].strip() for x in info["Author-email"].split(",")])
+copyright = f"{datetime.now():%Y}, {author}."
+version = info["Version"]
+urls = dict(pu.split(", ") for pu in info.get_all("Project-URL"))
+repository_url = urls["Homepage"]
+
+# The full version, including alpha/beta/rc tags
+release = info["Version"]
+
+bibtex_bibfiles = ["references.bib"]
+templates_path = ["_templates"]
+nitpicky = True  # Warn about broken links
+needs_sphinx = "4.0"
+
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "brickmanlab",
+    "github_repo": project_name,
+    "github_version": "master",
+    "conf_py_path": "/docs/",
+}
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings.
+# They can be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    "myst_nb",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.mathjax",
+    "IPython.sphinxext.ipython_console_highlighting",
+]
+
+autosummary_generate = True
+autodoc_member_order = "groupwise"
+default_role = "literal"
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_use_rtype = True  # having a separate entry generally helps readability
+napoleon_use_param = True
+myst_heading_anchors = 6  # create anchors for h1-h6
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+    "html_admonition",
+]
+myst_url_schemes = ("http", "https", "mailto")
+nb_output_stderr = "remove"
+nb_execution_mode = "off"
+nb_merge_streams = True
+typehints_defaults = "braces"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_book_theme"
+# html_static_path = ["_static"]
+# html_css_files = ["css/custom.css"]
+
+html_title = project_name
+
+html_theme_options = {
+    "repository_url": repository_url,
+    "use_repository_button": True,
+    "path_to_docs": "docs/",
+    "navigation_with_keys": False,
+}
+
+pygments_style = "default"
+
+nitpick_ignore = [
+    # If building the documentation fails because of a missing link that is outside your control,
+    # you can add an exception to this list.
+    #     ("py:class", "igraph.Graph"),
+]

docs/generated/scanvi_explainer.scanvi_deep.rst

@@ -0,0 +1,25 @@
+scanvi\_explainer.scanvi\_deep
+==============================
+
+.. automodule:: scanvi_explainer.scanvi_deep
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+
+      add_interim_values
+      deeplift_grad
+      deeplift_tensor_grad
+      get_target_input
+      linear_1d
+      maxpool
+      nonlinear_1d
+      passthrough
+
+   .. rubric:: Classes
+
+   .. autosummary::
+
+      SCANVIDeep
+

docs/index.md

@@ -0,0 +1,12 @@
+```{include} ../README.md
+
+```
+
+```{toctree}
+:hidden: true
+:maxdepth: 1
+
+api.md
+changelog.md
+notebooks/Example
+```

Example.ipynb → docs/notebooks/Example.ipynb

@@ -4,11 +4,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "---\n",
+    "# scANVI Explainer demo\n",
+    "\n",
     "date: 12-09-2024\n",
-    "author: Martin Proks\n",
-    "title: scANVI Explainer demo\n",
-    "---"
+    "\n",
+    "author: Martin Proks"
    ]
   },
   {
@@ -20,15 +20,6 @@
     "!which pip"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!pip list | grep scanvi_explainer"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/references.bib

@@ -0,0 +1,11 @@
+@article{Proks2024.02.16.580649,
+	author = {Proks, Martin and Salehin, Nazmus and Brickman, Joshua M.},
+	title = {Deep Learning Based Models for Preimplantation Mouse and Human Development},
+	elocation-id = {2024.02.16.580649},
+	year = {2024},
+	doi = {10.1101/2024.02.16.580649},
+	publisher = {Cold Spring Harbor Laboratory},
+	URL = {https://www.biorxiv.org/content/early/2024/02/16/2024.02.16.580649},
+	eprint = {https://www.biorxiv.org/content/early/2024/02/16/2024.02.16.580649.full.pdf},
+	journal = {bioRxiv}
+}

pyproject.toml

@@ -1,3 +1,7 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [project]
 name = "scanvi-explainer"
 version = "0.1.0"
@@ -23,16 +27,19 @@ classifiers = [
   "Programming Language :: Python :: 3.10"
 ]
 
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
 [project.urls]
 Homepage = "https://github.com/brickmanlab/scanvi-explainer"
-# Documentation = "https://readthedocs.org"
+Documentation = "https://readthedocs.org"
 Repository = "https://github.com/brickmanlab/scanvi-explainer.git"
 Issues = "https://github.com/brickmanlab/scanvi-explainer/issues"
 Changelog = "https://github.com/brickmanlab/scanvi-explainer/blob/master/CHANGELOG.md"
 
 [project.optional-dependencies]
 dev = ["ruff", "huggingface_hub"]
+doc = [
+  "setuptools",
+  "sphinx",
+  "myst-nb>=1.1",
+  "sphinx-book-theme>=1",
+  "sphinxcontrib-bibtex>=1"
+]