Update documentations

README.md

@@ -24,24 +24,24 @@ Currently implemented algorithms are:
 -   [scANVI](https://github.com/scverse/scvi-tools) label transfer
 -   [Celltypist](https://www.celltypist.org) cell type classification
 
-All algorithms are implemented as a class in [popv/algorithms](popv/algorithms/__init__.py).
+All algorithms are implemented as a class in [popv/algorithms](../popv/algorithms/__init__.py).
 To implement a new method, a class has to have several methods:
 
 -   algorithm._compute_integration: Computes dataset integration to yield an integrated latent space.
 -   algorithm.predict: Computes cell-type labels based on the specific classifier.
 -   algorithm._compute_embedding: Computes UMAP embedding of previously computed integrated latent space.
 
-New classifiers should inherit from [BaseAlgorithm](popv/algorithms/_base_algorithm.py). Adding a new class with those methods will automatically tell PopV to include this class into its classifiers and will use the new classifier as another expert.
+New classifiers should inherit from [BaseAlgorithm](../popv/algorithms/_base_algorithm.py). Adding a new class with those methods will automatically tell PopV to include this class into its classifiers and will use the new classifier as another expert.
 
 All algorithms that allow for pre-training are pre-trained. This excludes by design BBKNN, Harmony and SCANORAMA as all construct a new embedding space. Pretrained models are stored on (Zenodo)[https://zenodo.org/record/7580707] and are automatically downloaded in the Colab notebook linked below. We encourage pre-training models when implementing new classes.
 
-All input parameters are defined during initial call to [Process_Query](popv/preprocessing.py) and are stored in the unstructured field of the generated AnnData object. PopV has three levels of prediction complexities:
+All input parameters are defined during initial call to [Process_Query](../popv/preprocessing.py) and are stored in the unstructured field of the generated AnnData object. PopV has three levels of prediction complexities:
 
 -   retrain will train all classifiers from scratch. For 50k cells this takes up to an hour of computing time using a GPU.
 -   inference will use pretrained classifiers to annotate query as well as reference cells and construct a joint embedding using all integration methods from above. For 50k cells this takes in our hands up to half an hour of computing time using a GPU.
 -   fast will use only methods with pretrained classifiers to annotate only query cells. For 50k cells this takes 5 minutes without a GPU (without UMAP embedding).
 
-A user-defined selection of classification algorithms can be defined when calling [annotate_data](popv/annotation.py). Additionally advanced users can define here non-standard parameters for the integration methods as well as the classifiers.
+A user-defined selection of classification algorithms can be defined when calling [annotate_data](../popv/annotation.py). Additionally advanced users can define here non-standard parameters for the integration methods as well as the classifiers.
 
 ## Output
 
@@ -60,7 +60,7 @@ We suggest using a package manager like conda or mamba to install the package. O
 
 We provide an example notebook in Google Colab:
 
--   [Tutorial demonstrating use of Tabula sapiens as a reference](docs/notebooks/tabula_sapiens_tutorial.ipynb)
+-   [Tutorial demonstrating use of Tabula sapiens as a reference](../tabula_sapiens_tutorial.ipynb)
 
 This notebook will guide you through annotating a dataset based on the annotated [Tabula sapiens reference](https://tabula-sapiens-portal.ds.czbiohub.org) and demonstrates how to run annotation on your own query dataset. This notebook requires that all cells are annotated based on a cell ontology. We strongly encourage the use of a common cell ontology, see also [Osumi-Sutherland et al](https://www.nature.com/articles/s41556-021-00787-7). Using a cell ontology is a requirement to run OnClass as a prediction algorithm.
 

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # 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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.md

@@ -1,12 +1,49 @@
 # API
 
-## Preprocessing
+Import popV as:
+
+```
+import popv
+```
 
 ```{eval-rst}
-.. module:: popv
 .. currentmodule:: popv
 
-.. autosummary::
-    :toctree: generated
+```
+
+## Preprocessing
+
+Import as:
+```
+from popv.preprocessing import Process_Query
+```
+
+## Annotation pipeline
 
 ```
+from popv import algorithms
+```
+
+```{eval-rst}
+.. cpyturrentmodule:: popv
+
+```
+
+## Algorithms
+
+```{eval-rst}
+.. autosummary::
+   :toctree: reference/
+   :nosignatures:
+
+    algorithms.knn_on_scvi
+    algorithms.scanvi
+    "knn_on_bbknn",
+    "knn_on_harmony",
+    "svm",
+    "rf",
+    "onclass",
+    "knn_on_scanorama",
+    "celltypist",
+    "base_algorithm",
+

docs/conf.py

@@ -1,10 +1,16 @@
 # 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 --------------------------------------------------------------
+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
@@ -16,15 +22,13 @@
 
 # -- 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("PopV")
-project_name = info["Name"]
+project_name = "PopV"
+info = metadata(project_name)
+package_name = "popv"
 author = info["Author"]
 copyright = f"{datetime.now():%Y}, {author}."
 version = info["Version"]
-urls = dict(pu.split(", ") for pu in info.get_all("Project-URL"))
-repository_url = urls["Source"]
+repository_url = f"https://github.com/YosefLab/{project_name}"
 
 # The full version, including alpha/beta/rc tags
 release = info["Version"]
@@ -36,7 +40,7 @@
 
 html_context = {
     "display_github": True,  # Integrate GitHub
-    "github_user": "cane11",  # Username
+    "github_user": "yoseflab",  # Username
     "github_repo": project_name,  # Repo name
     "github_version": "main",  # Version
     "conf_py_path": "/docs/",  # Path in the checkout to the docs root
@@ -48,11 +52,13 @@
 # They can be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "myst_nb",
-    "sphinx_copybutton",
     "sphinx.ext.autodoc",
+    "sphinx_copybutton",
+    "sphinx.ext.linkcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
     "sphinxcontrib.bibtex",
     "sphinx_autodoc_typehints",
     "sphinx.ext.mathjax",
@@ -64,6 +70,7 @@
 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
@@ -91,16 +98,80 @@
 }
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
+    "ipython": ("https://ipython.readthedocs.io/en/stable/", None),
+    "matplotlib": ("https://matplotlib.org/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+    "python": ("https://docs.python.org/3", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "sklearn": ("https://scikit-learn.org/stable/", None),
+    "scanpy": ("https://scanpy.readthedocs.io/en/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"]
 
+# extlinks config
+extlinks = {
+    "issue": (f"{repository_url}/issues/%s", "#%s"),
+    "pr": (f"{repository_url}/pull/%s", "#%s"),
+    "ghuser": ("https://github.com/%s", "@%s"),
+}
+
+# -- 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:
+    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:
+        git_ref = "main"
+
+# https://github.com/DisnakeDev/disnake/blob/7853da70b13fcd2978c39c0b7efa59b34d298186/docs/conf.py#L192
+github_repo = "https://github.com/" + html_context["github_user"] + "/" + project_name
+_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:
+        return None
+
+    path = f"{path}#L{lineno}-L{lineno + len(src) - 1}"
+    return f"{github_repo}/blob/{git_ref}/src/{package_name}/{path}"
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -110,20 +181,31 @@
 html_theme = "sphinx_book_theme"
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
-
-html_title = project_name
+html_title = "popV"
 
 html_theme_options = {
-    "repository_url": repository_url,
+    "repository_url": github_repo,
     "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"),
 ]
+
+
+def setup(app):
+    """App setup hook."""
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "auto_toc_tree_section": "Contents",
+            "enable_auto_toc_tree": True,
+            "enable_math": True,
+            "enable_inline_math": False,
+            "enable_eval_rst": True,
+        },
+        True,
+    )

docs/index.md

@@ -7,9 +7,4 @@
 :maxdepth: 1
 
 api.md
-changelog.md
-contributing.md
-references.md
-
-notebooks/example
 ```