Backport PR scverse#1678: Doc touchups: linkcode, hoverxref, grid

meeseeksmachine · Sep 14, 2022 · 39d7a87 · 39d7a87
1 parent e47927b
commit 39d7a87
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 60 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,25 +1,12 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
-# scvi documentation build configuration file, created by
-# sphinx-quickstart on Fri Jun  9 13:47:02 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another
-# directory, add these directories to sys.path here. If the directory is
-# relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
-#
+import importlib.util
+import inspect
+import os
+import subprocess
 import sys
+import re
+
 from pathlib import Path
+from typing import Any
 
 HERE = Path(__file__).parent
 sys.path[:0] = [str(HERE.parent), str(HERE / "extensions")]
@@ -38,7 +25,7 @@
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "nbsphinx",
     "nbsphinx_link",
     "sphinx.ext.mathjax",
@@ -54,7 +41,10 @@
     "sphinx_remove_toctrees",
     "sphinx_design",
     "sphinxext.opengraph",
+    "hoverxref.extension",
 ]
+github_repo = "https://github.com/scverse/scvi-tools"
+
 
 # remove_from_toctrees = ["tutorials/notebooks/*", "api/reference/*"]
 
@@ -123,6 +113,27 @@
 # The full version, including alpha/beta/rc tags.
 release = scvi.__version__
 
+
+def git(*args):
+    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 = "master"
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -169,6 +180,8 @@
 html_css_files = ["css/override.css", "css/sphinx_gallery.css"]
 html_show_sphinx = False
 
+# --------------------------------------------------------
+
 
 nbsphinx_prolog = r"""
 .. raw:: html
@@ -241,3 +254,48 @@
     "tutorials/notebooks/cell2location_lymph_node_spatial_tutorial": "_static/tutorials/cell2location.png",
     "tutorials/notebooks/tabula_muris": "_static/tutorials/muris-mouse.png",
 }
+
+# https://github.com/DisnakeDev/disnake/blob/7853da70b13fcd2978c39c0b7efa59b34d298186/docs/conf.py#L192
+_scvi_tools_module_path = os.path.dirname(importlib.util.find_spec("scvi").origin)  # type: ignore
+
+
+def linkcode_resolve(domain, info):
+    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=_scvi_tools_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}/scvi/{path}"
+
+
+hoverx_default_type = "tooltip"
+hoverxref_domains = ["py"]
+hoverxref_role_types = dict.fromkeys(
+    ["ref", "class", "func", "meth", "attr", "exc", "data"],
+    "tooltip",
+)
+hoverxref_intersphinx = [
+    "python",
+    "numpy",
+    "scanpy",
+    "anndata",
+    "pytorch_lightning",
+    "scipy",
+    "pandas",
+]
+# use proxied API endpoint on rtd to avoid CORS issues
+if os.environ.get("READTHEDOCS"):
+    hoverxref_api_host = "/_"
diff --git a/docs/index.md b/docs/index.md
@@ -7,57 +7,53 @@
 
 If you find a model useful for your research, please consider citing the [scvi-tools manuscript](http://dx.doi.org/10.1038/s41587-021-01206-w) as well as the publication describing the model, which can be found in the corresponding documentation.
 
-```{eval-rst}
-.. card:: Installation :octicon:`plug;1em;`
-    :link: installation
-    :link-type: doc
+::::{grid} 3
+:gutter: 2
 
-    New to *scvi-tools*? Check out the installation guide.
-```
+:::{grid-item-card} Installation {octicon}`plug;1em;`
+:link: installation
+:link-type: doc
 
-```{eval-rst}
-.. card:: User guide :octicon:`info;1em;`
-    :link: user_guide/index
-    :link-type: doc
+New to *scvi-tools*? Check out the installation guide.
+:::
 
-    The user guide provides distilled mathematical descriptions of
-    the models implemented in scvi-tools and connects the math
-    with the code.
-```
+:::{grid-item-card} User guide {octicon}`info;1em;`
+:link: user_guide/index
+:link-type: doc
 
-```{eval-rst}
-.. card:: API reference :octicon:`book;1em;`
-    :link: api/index
-    :link-type: doc
+The user guide provides distilled mathematical descriptions of
+the models implemented in scvi-tools and connects the math
+with the code.
+:::
 
-    The API reference contains a detailed description of
-    the scvi-tools API.
-```
+:::{grid-item-card} API reference {octicon}`book;1em;`
+:link: api/index
+:link-type: doc
 
-```{eval-rst}
-.. card:: Tutorials :octicon:`play;1em;`
-    :link: tutorials/index
-    :link-type: doc
+The API reference contains a detailed description of
+the scvi-tools API.
+:::
 
-    The tutorials walk you through real-world applications of scvi-tools models.
-    Developer tutorials help you build new probabilistic models.
-```
+:::{grid-item-card} Tutorials {octicon}`play;1em;`
+:link: tutorials/index
+:link-type: doc
 
-```{eval-rst}
-.. card:: Discussion :octicon:`megaphone;1em;`
-    :link: https://discourse.scvi-tools.org
+The tutorials walk you through real-world applications of scvi-tools models.
+Developer tutorials help you build new probabilistic models.
+:::
 
-    Need help? Reach out on our forum to get your questions answered!
+:::{grid-item-card} Discussion {octicon}`megaphone;1em;`
+:link: https://discourse.scvi-tools.org
 
-```
-
-```{eval-rst}
-.. card:: GitHub :octicon:`mark-github;1em;`
-    :link: https://github.com/yoseflab/scvi-tools
+Need help? Reach out on our forum to get your questions answered!
+:::
 
-    Find a bug? Interested in improving scvi-tools? Checkout our GitHub for the latest developments.
+:::{grid-item-card} GitHub {octicon}`mark-github;1em;`
+:link: https://github.com/yoseflab/scvi-tools
 
-```
+Find a bug? Interested in improving scvi-tools? Checkout our GitHub for the latest developments.
+:::
+::::
 
 ```{toctree}
 :hidden: true

diff --git a/pyproject.toml b/pyproject.toml
@@ -75,6 +75,7 @@ sphinx = {version = ">=4.1", optional = true}
 sphinx-autodoc-typehints = {version = "*", optional = true}
 sphinx-design = {version = "*", optional = true}
 sphinx-gallery = {version = ">0.6,<0.11", optional = true}
+sphinx-hoverxref = {version = "*", optional = true}
 sphinx_copybutton = {version = "<=0.3.1", optional = true}
 sphinx_remove_toctrees = {version = "*", optional = true}
 sphinxext-opengraph = {version = "*", optional = true}
@@ -99,6 +100,7 @@ docs = [
   "sphinx_remove_toctrees",
   "sphinx-design",
   "sphinxext-opengraph",
+  "sphinx-hoverxref",
   "myst-parser",
 ]
 pymde = ["pymde"]