Merge pull request #9 from czbiohub-sf/improve_docs

Improve docs

Author: mffrank

Makefile

@@ -2,7 +2,8 @@ PACKAGE_NAME := grassp
 
 .PHONY: setup-develop
 setup-develop:
-	pip install -e .'[dev,docs,notebook]'
+	pip install -e .'[dev, docs, notebook]'
+
 	pre-commit install
 
 .PHONY: uninstall

docs/source/_static/custom.css

@@ -1,7 +1,18 @@
 /* Adjust sidebar width */
-.bd-sidebar {
-    min-width: 300px;  /* Increase from default */
-    max-width: 450px; /* Set maximum width */
+/* Wider left sidebar so long function names are not truncated */
+
+/* For PyData Sphinx Theme >= 0.13 */
+:root {
+    /* Primary sidebar width */
+    --pst-sidebar-primary: 400px;
+}
+
+/* For older/alternate class names */
+.bd-sidebar,
+.bd-sidebar-primary {
+    flex: 0 0 400px;   /* fixed width */
+    max-width: 400px;
+    min-width: 400px;
 }
 
 /* Ensure content adjusts properly */

docs/source/api/plotting.md

@@ -1,4 +1,4 @@
-## Plotting: `pl`
+# Plotting: `pl`
 
 ```{eval-rst}
 .. module:: grassp.pl
@@ -11,10 +11,10 @@
 This module provides visualization functions for proteomics data.
 
 ```{note}
-Many of scanpy's plotting functions can be directly used with grassp AnnData objects. So if you are looking for a specific plot, it is worth checking if it is already implemented in scanpy.
+Many of [Scanpy's plotting](https://scanpy.readthedocs.io/en/stable/api/plotting.html) functions can be used directly with grassp AnnData objects. If you are looking for a specific plot, check whether it is already implemented in Scanpy.
 ```
 
-### Preprocessing
+## Preprocessing
 
 ```{eval-rst}
 .. autosummary::
@@ -24,9 +24,10 @@ Many of scanpy's plotting functions can be directly used with grassp AnnData obj
    pl.highly_variable_proteins
    pl.bait_volcano_plots
    pl.protein_clustermap
+   pl.sample_heatmap
 ```
 
-### Integration
+## Integration
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
@@ -35,13 +36,26 @@ Many of scanpy's plotting functions can be directly used with grassp AnnData obj
    pl.aligned_umap
    pl.remodeling_score
    pl.remodeling_sankey
-``` 
+   pl.mr_plot
+```
 
-### Clustering
+## Clustering
 ```{eval-rst}
 .. autosummary::
    :nosignatures:
    :toctree: ../generated/
 
+   pl.qsep_heatmap
+   pl.qsep_boxplot
    pl.tagm_map_contours
-   pl.tagm_map_pca_ellipses
+   pl.tagm_map_pca_ellipses
+```
+
+## Ternary
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   pl.ternary
+```

docs/source/api/preprocessing.md

@@ -1,4 +1,4 @@
-## Preprocessing: `pp`
+# Preprocessing: `pp`
 
 ```{eval-rst}
 .. module:: grassp.pp
@@ -10,7 +10,7 @@
 
 Any transformation of the data matrix that is not a *tool*. Other than *tools*, preprocessing steps usually don't return an easily interpretable annotation, but perform a basic transformation on the data matrix.
 
-### Basic Preprocessing
+## Basic Preprocessing
 
 
 ```{eval-rst}
@@ -31,7 +31,18 @@ Any transformation of the data matrix that is not a *tool*. Other than *tools*,
    pp.filter_min_consecutive_fractions
 ```
 
-### Imputation
+## Enrichment
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
+
+   pp.calculate_enrichment_vs_untagged
+   pp.calculate_enrichment_vs_all
+```
+
+## Imputation
 
 ```{eval-rst}
 .. autosummary::

docs/source/api/tools.md

@@ -1,4 +1,4 @@
-## Tools: `tl`
+# Tools: `tl`
 
 ```{eval-rst}
 .. module:: grassp.tl
@@ -8,9 +8,9 @@
 .. currentmodule:: grassp
 ```
 
-This module provides various tools for analyzing proteomics data. 
+This module provides various tools for analyzing proteomics data.
 
-### Clustering
+## Clustering
 
 ```{eval-rst}
 .. autosummary::
@@ -20,14 +20,13 @@ This module provides various tools for analyzing proteomics data.
    tl.leiden_mito_sweep
    tl.knn_annotation
    tl.calculate_interfacialness_score
-   tl.get_n_nearest_neighbors
    tl.silhouette_score
    tl.calinski_habarasz_score
    tl.tagm_map_train
    tl.tagm_map_predict
 ```
 
-### Enrichment
+## Ontology Enrichment
 
 ```{eval-rst}
 .. autosummary::
@@ -38,7 +37,7 @@ This module provides various tools for analyzing proteomics data.
 ```
 
 
-### Integration
+## Integration
 
 ```{eval-rst}
 .. autosummary::
@@ -48,5 +47,15 @@ This module provides various tools for analyzing proteomics data.
    tl.align_adatas
    tl.aligned_umap
    tl.remodeling_score
+```
+
+## Graph analysis
+
+```{eval-rst}
+.. autosummary::
+   :nosignatures:
+   :toctree: ../generated/
 
-```
+   tl.to_knn_graph
+   tl.get_n_nearest_neighbors
+```

docs/source/conf.py

@@ -25,6 +25,7 @@
     "sphinx.ext.githubpages",
     "sphinx.ext.autosummary",
     "sphinx_autodoc_typehints",
+    "sphinx.ext.intersphinx",
     "scanpydoc",
     "myst_nb",  # enable notebook execution and rendering (includes myst_parser)
 ]
@@ -57,6 +58,15 @@
 html_logo = "_static/img/grassp_logo.png"
 issues_github_path = "czbiohub-sf/grassp"
 html_show_sphinx = False
+intersphinx_mapping = dict(
+    python=("https://docs.python.org/3", None),
+    numpy=("https://numpy.org/doc/stable", None),
+    pandas=("https://pandas.pydata.org/pandas-docs/stable", None),
+    anndata=("https://anndata.readthedocs.io/en/stable/", None),
+    scanpy=("https://scanpy.readthedocs.io/en/stable/", None),
+    scipy=("https://docs.scipy.org/doc/scipy", None),
+)
+
 
 # Execute notebooks only when out-of-date and set timeout
 nb_execution_mode = "auto"  # or "force" to always run, "off" to skip

docs/source/generated/grassp.pl.mr_plot.rst

@@ -0,0 +1,6 @@
+grassp.pl.mr\_plot
+==================
+
+.. currentmodule:: grassp.pl
+
+.. autofunction:: mr_plot

docs/source/generated/grassp.pl.qsep_boxplot.rst

@@ -0,0 +1,6 @@
+grassp.pl.qsep\_boxplot
+=======================
+
+.. currentmodule:: grassp.pl
+
+.. autofunction:: qsep_boxplot

docs/source/generated/grassp.pl.qsep_heatmap.rst

@@ -0,0 +1,6 @@
+grassp.pl.qsep\_heatmap
+=======================
+
+.. currentmodule:: grassp.pl
+
+.. autofunction:: qsep_heatmap

docs/source/generated/grassp.pl.sample_heatmap.rst

@@ -0,0 +1,6 @@
+grassp.pl.sample\_heatmap
+=========================
+
+.. currentmodule:: grassp.pl
+
+.. autofunction:: sample_heatmap