add usage docs

HiDiHlabs · Jul 16, 2024 · 7a2b4ae · 7a2b4ae
1 parent 77c59ad
commit 7a2b4ae
Show file tree

Hide file tree

Showing 7 changed files with 1,107 additions and 7 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,6 +5,7 @@ repos:
     rev: v4.6.0
     hooks:
       - id: check-added-large-files
+        exclude: "usage.ipynb"
       - id: check-case-conflict
       - id: check-toml
       - id: check-yaml
@@ -42,6 +43,7 @@ repos:
     rev: v2.3.0
     hooks:
       - id: codespell
+        exclude_types: ["jupyter"]
         additional_dependencies:
           - tomli
   - repo: https://github.com/google/yamlfmt

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,8 @@
+# setuptools-scm includes all tracked files by default in sdist
+
+# exclude docs as it contains large files
+prune docs
+
+# exclude unnecessary configs
+exclude .pre-commit-config.yaml .readthedocs.yaml .yamlfmt.yaml
+prune .github
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -26,8 +26,11 @@
     "sphinx.ext.napoleon",
     "autoapi.extension",
     "sphinx.ext.mathjax",
+    "myst_nb",
 ]
 
+nb_execution_mode = "off"
+
 
 autodoc_typehints = "none"
 autodoc_typehints_format = "short"

diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
@@ -8,7 +8,7 @@ The data can be filtered, subset, and cropped to adjust the desired field of vie
 genes.
 
 In the next step the kernel for kernel density estimation (KDE) is defined and
-cell types are assigned to each pixel using cell type gene
+cell types are assigned to each pixel using cell-type gene
 expression signatures from e.g. single-cell RNAseq.
 
 Otherwise you can find the local maxima of the KDE and treat these as proxies for cells.
@@ -19,5 +19,5 @@ spatial methods (e.g. using `scanpy <https://scanpy.readthedocs.io/en/stable/>`_
 Along the way you will want to (and should) generate a lot of plots to check your
 results.
 
-For a more concrete example of what a workflow can look like we will provide example
-notebooks soon.
+For a more concrete example of what a workflow looks like check out the
+:doc:`usage` guide.
diff --git a/docs/source/usage.ipynb b/docs/source/usage.ipynb
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
diff --git a/pyproject.toml b/pyproject.toml
@@ -41,8 +41,14 @@ classifiers = [
 
 [project.optional-dependencies]
 spatialdata = ["spatialdata>=0.1"]
-docs        = ["sphinx", "sphinx-autoapi>=3.1", "sphinx-copybutton", "sphinx-rtd-theme"]
-dev         = ["sainsc[docs]", "pre-commit"]
+docs = [
+    "sphinx",
+    "sphinx-autoapi>=3.1",
+    "sphinx-copybutton",
+    "sphinx-rtd-theme",
+    "myst-nb",
+]
+dev = ["sainsc[docs,spatialdata]", "pre-commit"]
 
 [project.urls]
 homepage      = "https://github.com/HiDiHlabs/sainsc"