fix Edit on GitHub (#4460)

* try to point sphinx_rtd_theme to the correct url

* register the jinja filter using the setup function

* fix the template

* use scanpydoc instead of a copy

* fix the use of scanpydoc

* escape underscores in github urls

* don't override conf_py_path, RTD correctly detects that

Author: keewis

ci/requirements/doc.yml

@@ -28,5 +28,6 @@ dependencies:
   - zarr>=2.4
   - pip
   - pip:
+      - scanpydoc
       # relative to this file. Needs to be editable to be accepted.
       - -e ../..

doc/_templates/autosummary/base.rst

@@ -0,0 +1,3 @@
+:github_url: {{ fullname | github_url | escape_underscores }}
+
+{% extends "!autosummary/base.rst" %}

doc/conf.py

@@ -14,11 +14,13 @@
 
 import datetime
 import os
+import pathlib
 import subprocess
 import sys
 from contextlib import suppress
 
 import sphinx_autosummary_accessors
+from jinja2.defaults import DEFAULT_FILTERS
 
 import xarray
 
@@ -78,6 +80,7 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "nbsphinx",
     "sphinx_autosummary_accessors",
+    "scanpydoc.rtd_github_links",
 ]
 
 extlinks = {
@@ -97,6 +100,15 @@
 """
 
 autosummary_generate = True
+
+# for scanpydoc's jinja filter
+project_dir = pathlib.Path(__file__).parent.parent
+html_context = {
+    "github_user": "pydata",
+    "github_repo": "xarray",
+    "github_version": "master",
+}
+
 autodoc_typehints = "none"
 
 napoleon_use_param = False
@@ -404,3 +416,11 @@
     "dask": ("https://docs.dask.org/en/latest", None),
     "cftime": ("https://unidata.github.io/cftime", None),
 }
+
+
+def escape_underscores(string):
+    return string.replace("_", r"\_")
+
+
+def setup(app):
+    DEFAULT_FILTERS["escape_underscores"] = escape_underscores