Add extremely elaborate R link impl

Author: flying-sheep

README.rst

@@ -2,29 +2,34 @@
 
 .. |pypi| image:: https://img.shields.io/pypi/v/anndata2ri
    :target: https://pypi.org/project/anndata2ri/
+   :alt: PyPI Version
 
 .. |conda| image:: https://img.shields.io/conda/vn/bioconda/anndata2ri
    :target: https://anaconda.org/bioconda/anndata2ri
+   :alt: Bioconda Version
 
 .. |rtd| image:: https://readthedocs.com/projects/icb-anndata2ri/badge/?version=latest&token=ee358f7efe36cbbd7d04db1b708fa81cefc44634ae7f3f8e0afcd03a1f0b1158
-   :target: https://icb-anndata2ri.readthedocs-hosted.com/en/latest/?badge=latest
+   :target: docs_
    :alt: Documentation Status
 
 .. |travis| image:: https://travis-ci.org/theislab/anndata2ri.svg?branch=master
    :target: https://travis-ci.org/theislab/anndata2ri
+   :alt: Travis CI Status
 
 .. |doi| image:: https://zenodo.org/badge/171714778.svg
    :target: https://zenodo.org/badge/latestdoi/171714778
+   :alt: Publication DOI
 
 AnnData ↭ SingleCellExperiment
 ==============================
 
-RPy2 converter from AnnData_ to SingleCellExperiment_ and back.
+RPy2 converter from AnnData_ to SingleCellExperiment_ and back. (For **details about conversion** see the docs_)
 
 You can for example use it to process your data using both Scanpy_ and Seurat_, as described in this `example notebook`_
 
 .. _AnnData: https://anndata.readthedocs.io/en/latest/
 .. _SingleCellExperiment: http://bioconductor.org/packages/release/bioc/vignettes/SingleCellExperiment/inst/doc/intro.html
+.. _docs: https://icb-anndata2ri.readthedocs-hosted.com/en/latest/
 .. _Scanpy: https://scanpy.readthedocs.io/en/stable/
 .. _Seurat: https://satijalab.org/seurat/
 .. _`example notebook`: https://github.com/LuckyMD/Code_snippets/blob/master/Seurat_to_anndata.ipynb

anndata2ri/__init__.py

@@ -1,5 +1,18 @@
-"""
+r"""
 Converter between Python’s AnnData and R’s SingleCellExperiment.
+
+
+==========================================================  =====  ================================================
+:rcls:`~SingleCellExperiment::SingleCellExperiment`                :class:`~anndata.AnnData`
+==========================================================  =====  ================================================
+:rman:`~SummarizedExperiment::assay`\ ``(d, 'X')``          ⇄      :attr:`~anndata.AnnData.X`
+:rman:`~SummarizedExperiment::assay`\ ``(d, 'counts')``     ⇄      :attr:`~anndata.AnnData.layers`\ ``['counts']``
+:rman:`~SummarizedExperiment::colData`\ ``(d)``             ⇄      :attr:`~anndata.AnnData.obs`
+:rman:`~SummarizedExperiment::rowData`\ ``(d)``             ⇄      :attr:`~anndata.AnnData.var`
+:rman:`~S4Vectors::metadata`\ ``(d)``                       ⇄      :attr:`~anndata.AnnData.uns`
+:rman:`~SingleCellExperiment::reducedDim`\ ``(d, 'PCA')``   ⇄      :attr:`~anndata.AnnData.obsm`\ ``['X_pca']``
+:rman:`~SingleCellExperiment::reducedDim`\ ``(d, 'DM')``    ⇄      :attr:`~anndata.AnnData.obsm`\ ``['X_diffmap']``
+==========================================================  =====  ================================================
 """
 __all__ = ["activate", "deactivate", "py2rpy", "rpy2py", "converter"]
 

docs/_static/css/custom.css

@@ -0,0 +1,11 @@
+/* Make things like :func:`foo`\\ ``bar`` have no visible gap */
+table a.reference.external + code {
+    border-left: 0;
+    margin-left: -6px;
+    padding-left: 0;
+}
+
+/* Make sure columns don’t wrongly derive width from rst code */
+table.docutils col {
+    width: auto !important;
+}

docs/conf.py

@@ -1,12 +1,5 @@
-from typing import Tuple
 from unittest.mock import MagicMock
 
-from docutils import nodes
-from sphinx.application import Sphinx
-from sphinx.environment import BuildEnvironment
-from sphinx.roles import XRefRole
-
-
 import sys
 from pathlib import Path
 from datetime import datetime
@@ -20,15 +13,16 @@
 submods = ["embedded", "conversion", "memorymanagement", "sexp", "bufferprotocol", "callbacks", "_rinterface_capi"]
 sys.modules.update({f"rpy2.rinterface_lib.{sub}": MagicMock() for sub in submods})
 sexp = sys.modules["rpy2.rinterface_lib.sexp"]
-sexp.Sexp = sexp.SexpVector = sexp.SexpEnvironment = sexp.StrSexpVector = MagicMock
+sexp.Sexp = type("Sexp", (MagicMock,), dict(__module__="rpy2.rinterface"))
+sexp.SexpVector = sexp.SexpEnvironment = sexp.StrSexpVector = MagicMock
 sexp.SexpVector.from_iterable = MagicMock()
 
 import rpy2.rinterface
 
 rpy2.rinterface._MissingArgType = object
 
 # now we can import it!
-sys.path.insert(0, str(HERE.parent))
+sys.path[:0] = [str(HERE.parent), str(HERE / "ext")]
 import anndata2ri.scipy2ri  # noqa
 
 
@@ -58,6 +52,7 @@
     "sphinx.ext.autosummary",
     "sphinx_autodoc_typehints",
     "scanpydoc",
+    *[p.stem for p in (HERE / "ext").glob("*.py")],
 ]
 
 # Generate the API documentation when building
@@ -85,6 +80,8 @@
 
 html_theme = "scanpydoc"
 html_theme_options = dict(collapse_navigation=True)
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 html_context = dict(
     display_github=True,
     github_user="theislab",
@@ -94,51 +91,6 @@
 )
 
 
-# -- Add R links ----------------------------------------------------------
-
-
-class RManRefRole(XRefRole):
-    nodeclass = nodes.reference
-
-    def __init__(self, *a, cls: bool = False, **kw):
-        super().__init__(*a, **kw)
-        self.cls = cls
-
-    def process_link(
-        self, env: BuildEnvironment, refnode: nodes.reference, has_explicit_title: bool, title: str, target: str
-    ) -> Tuple[str, str]:
-        qualified = not target.startswith("~")
-        if not qualified:
-            target = target[1:]
-        package, symbol = target.split("::")
-        title = target if qualified else symbol
-        topic = symbol
-        if self.cls:
-            topic += "-class"
-        target = f"https://www.rdocumentation.org/packages/{package}/topics/{topic}"
-        refnode["refuri"] = target
-        return title, target
-
-    # def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: nodes.reference, is_ref: bool):
-    #    target = node.get('reftarget')
-    #    if target:
-    #        node.attributes['refuri'] = target
-    #    return [node], []
-
-
-def setup(app: Sphinx):
-    app.add_role("rman", RManRefRole())
-    app.add_role("rcls", RManRefRole(cls=True))
-
-
-# -- Quick fixes ---------------------------------------------------------------
-
-
-from rpy2.rinterface import Sexp
-
-Sexp.__module__ = "rpy2.rinterface"
-
-
 # -- Options for other output formats ------------------------------------------
 
 

docs/ext/r_links.py

@@ -0,0 +1,84 @@
+import logging
+from typing import Tuple
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.environment import BuildEnvironment
+from sphinx.roles import XRefRole
+
+
+class RManRefRole(XRefRole):
+    nodeclass = nodes.reference
+
+    topic_cache = {}
+
+    def __init__(self, *a, cls: bool = False, **kw):
+        super().__init__(*a, **kw)
+        self.cls = cls
+
+    def _get_man(self, pkg: str, alias: str):
+        from urllib.error import HTTPError
+
+        pkg_cache = type(self).topic_cache.setdefault(pkg)
+        if not pkg_cache:
+            for repo in ["R-patched", "cran", "bioc"]:
+                try:
+                    pkg_cache = self._fetch_cache(repo, pkg)
+                    break
+                except HTTPError:
+                    pass
+            else:
+                return None
+            type(self).topic_cache[pkg] = pkg_cache
+        return pkg_cache.get(alias)
+
+    def _fetch_cache(self, repo: str, pkg: str):
+        from lxml import html
+        from urllib.request import urlopen
+        from urllib.parse import urljoin
+
+        if repo.startswith("R"):
+            url = f"https://stat.ethz.ch/R-manual/{repo}/library/{pkg}/html/00Index.html"
+            tr_xpath = "//tr"
+            get = lambda tr: (tr[0][0].text, tr[0][0].attrib["href"])
+        else:
+            url = f"https://rdrr.io/{repo}/{pkg}/api/"
+            tr_xpath = "//div[@id='body-content']//tr[./td]"
+            get = lambda tr: (tr[0].text, tr[1][0].attrib["href"])
+
+        with urlopen(url) as con:
+            txt = con.read().decode(con.headers.get_content_charset())
+        doc = html.fromstring(txt)
+        cache = {}
+        for tr in doc.xpath(tr_xpath):
+            topic, href = get(tr)
+            cache[topic] = urljoin(url, href)
+        return cache
+
+    def process_link(
+        self, env: BuildEnvironment, refnode: nodes.reference, has_explicit_title: bool, title: str, target: str
+    ) -> Tuple[str, str]:
+        qualified = not target.startswith("~")
+        if not qualified:
+            target = target[1:]
+        package, symbol = target.split("::")
+        title = target if qualified else symbol
+        topic = symbol
+        if self.cls:
+            topic += "-class"
+        url = self._get_man(package, topic)
+        refnode["refuri"] = url
+        if not url:
+            logging.warning(f"R topic {target} not found.")
+        return title, url
+
+    # def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: nodes.reference, is_ref: bool):
+    #    target = node.get('reftarget')
+    #    if target:
+    #        node.attributes['refuri'] = target
+    #    return [node], []
+
+
+def setup(app: Sphinx):
+    app.add_role("rman", RManRefRole())
+    app.add_role("rcls", RManRefRole(cls=True))

pyproject.toml

@@ -35,6 +35,7 @@ doc = [
     'sphinx>=3.0',
     'sphinx-autodoc-typehints',
     'scanpydoc',
+    'lxml',  # For scraping the R link info
 ]
 
 [tool.flit.metadata.urls]