Add references, linkcode to docs, remove scanpydoc (#25)

* update references

* ref style

* no scanpydoc

* try return

* try return

* typehint defaults

* add linkcode

.flake8

@@ -46,6 +46,8 @@ rst-roles =
     class,
     func,
     ref,
+    cite:p,
+    cite:t,
 rst-directives =
     envvar,
     exception,

docs/conf.py

@@ -5,6 +5,12 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
+from typing import Any
+import subprocess
+import os
+import importlib
+import inspect
+import re
 import sys
 from datetime import datetime
 from importlib.metadata import metadata
@@ -45,19 +51,20 @@
 extensions = [
     "myst_nb",
     "sphinx.ext.autodoc",
+    "sphinx.ext.linkcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinxcontrib.bibtex",
     "sphinx_autodoc_typehints",
-    "scanpydoc.elegant_typehints",
     "sphinx.ext.mathjax",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 
 autosummary_generate = True
 autodoc_member_order = "groupwise"
 default_role = "literal"
+bibtex_reference_style = "author_year"
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_include_init_with_doc = False
@@ -76,6 +83,7 @@
 nb_output_stderr = "remove"
 nb_execution_mode = "off"
 nb_merge_streams = True
+typehints_defaults = "braces"
 
 source_suffix = {
     ".rst": "restructuredtext",
@@ -101,6 +109,58 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
+# -- Linkcode settings -------------------------------------------------
+
+
+def git(*args):
+    """Run a git command and return the output."""
+    return subprocess.check_output(["git", *args]).strip().decode()
+
+
+# https://github.com/DisnakeDev/disnake/blob/7853da70b13fcd2978c39c0b7efa59b34d298186/docs/conf.py#L192
+# Current git reference. Uses branch/tag name if found, otherwise uses commit hash
+git_ref = None
+try:
+    git_ref = git("name-rev", "--name-only", "--no-undefined", "HEAD")
+    git_ref = re.sub(r"^(remotes/[^/]+|tags)/", "", git_ref)
+except Exception:  # noqa: B902
+    pass
+
+# (if no name found or relative ref, use commit hash instead)
+if not git_ref or re.search(r"[\^~]", git_ref):
+    try:
+        git_ref = git("rev-parse", "HEAD")
+    except Exception:  # noqa: B902
+        git_ref = "main"
+
+# https://github.com/DisnakeDev/disnake/blob/7853da70b13fcd2978c39c0b7efa59b34d298186/docs/conf.py#L192
+# If package name differs from the project name, set it here
+package_name = project
+_project_module_path = os.path.dirname(importlib.util.find_spec(package_name).origin)  # type: ignore
+
+
+def linkcode_resolve(domain, info):
+    """Resolve links for the linkcode extension."""
+    if domain != "py":
+        return None
+
+    try:
+        obj: Any = sys.modules[info["module"]]
+        for part in info["fullname"].split("."):
+            obj = getattr(obj, part)
+        obj = inspect.unwrap(obj)
+
+        if isinstance(obj, property):
+            obj = inspect.unwrap(obj.fget)  # type: ignore
+
+        path = os.path.relpath(inspect.getsourcefile(obj), start=_project_module_path)  # type: ignore
+        src, lineno = inspect.getsourcelines(obj)
+    except Exception:  # noqa: B902
+        return None
+
+    path = f"{path}#L{lineno}-L{lineno + len(src) - 1}"
+    return f"{project}/blob/{git_ref}/{package_name}/{path}"
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -117,7 +177,6 @@
 }
 
 pygments_style = "default"
-pygments_dark_style = "native"
 
 nitpick_ignore = [
     # If building the documentation fails because of a missing link that is outside your control,

docs/references.bib

@@ -1,17 +1,10 @@
-@article{Wolf2018,
-  author   = {Wolf, F. Alexander
-              and Angerer, Philipp
-              and Theis, Fabian J.},
-  title    = {SCANPY: large-scale single-cell gene expression data analysis},
-  journal  = {Genome Biology},
-  year     = {2018},
-  month    = {Feb},
-  day      = {06},
-  volume   = {19},
-  number   = {1},
-  pages    = {15},
-  abstract = {Scanpy is a scalable toolkit for analyzing single-cell gene expression data. It includes methods for preprocessing, visualization, clustering, pseudotime and trajectory inference, differential expression testing, and simulation of gene regulatory networks. Its Python-based implementation efficiently deals with data sets of more than one million cells (https://github.com/theislab/Scanpy). Along with Scanpy, we present AnnData, a generic class for handling annotated data matrices (https://github.com/theislab/anndata).},
-  issn     = {1474-760X},
-  doi      = {10.1186/s13059-017-1382-0},
-  url      = {https://doi.org/10.1186/s13059-017-1382-0}
+@article{luecken2022benchmarking,
+  title     = {Benchmarking atlas-level data integration in single-cell genomics},
+  author    = {Luecken, Malte D and B{\"u}ttner, Maren and Chaichoompu, Kridsadakorn and Danese, Anna and Interlandi, Marta and M{\"u}ller, Michaela F and Strobl, Daniel C and Zappia, Luke and Dugas, Martin and Colom{\'e}-Tatch{\'e}, Maria and others},
+  journal   = {Nature methods},
+  volume    = {19},
+  number    = {1},
+  pages     = {41--50},
+  year      = {2022},
+  publisher = {Nature Publishing Group}
 }

src/scib_metrics/_isolated_labels.py

@@ -15,7 +15,7 @@ def isolated_labels(
     batch: np.ndarray,
     iso_threshold: Optional[int] = None,
 ) -> float:
-    """Isolated label score.
+    """Isolated label score :cite:p:`luecken2022benchmarking`.
 
     Score how well labels of isolated labels are distiguished in the dataset by
     average-width silhouette score (ASW) on isolated label vs all other labels.

src/scib_metrics/_silhouette.py

@@ -5,7 +5,7 @@
 
 
 def silhouette_label(X: np.ndarray, labels: np.ndarray, rescale: bool = True) -> float:
-    """Average silhouette width (ASW).
+    """Average silhouette width (ASW) :cite:p:`luecken2022benchmarking`.
 
     Parameters
     ----------
@@ -27,7 +27,7 @@ def silhouette_label(X: np.ndarray, labels: np.ndarray, rescale: bool = True) ->
 
 
 def silhouette_batch(X: np.ndarray, labels: np.ndarray, batch: np.ndarray, rescale: bool = True) -> float:
-    """Average silhouette width (ASW) with respect to batch ids within each label.
+    """Average silhouette width (ASW) with respect to batch ids within each label :cite:p:`luecken2022benchmarking`.
 
     Parameters
     ----------

src/scib_metrics/utils/_silhouette.py

@@ -105,9 +105,7 @@ def silhouette_samples(X: np.ndarray, labels: np.ndarray) -> np.ndarray:
 
     Returns
     -------
-    silhouette
-        Array of shape (n_samples,)
-        Silhouette Coefficients for each sample.
+    silhouette scores array of shape (n_samples,)
     """
     if X.shape[0] != labels.shape[0]:
         raise ValueError("X and labels should have the same number of samples")