From b232f66764282ed2754cb67543eb2cefe1b52688 Mon Sep 17 00:00:00 2001 From: Keewis Date: Thu, 13 Aug 2020 01:54:29 +0200 Subject: [PATCH 1/7] try to point sphinx_rtd_theme to the correct url --- doc/_templates/edit_on_github.rst | 3 +++ doc/conf.py | 15 +++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 doc/_templates/edit_on_github.rst diff --git a/doc/_templates/edit_on_github.rst b/doc/_templates/edit_on_github.rst new file mode 100644 index 00000000000..163d9d80c6a --- /dev/null +++ b/doc/_templates/edit_on_github.rst @@ -0,0 +1,3 @@ +:github_url: {{ full_name | github_url }} + +{% extends base.rst %} diff --git a/doc/conf.py b/doc/conf.py index 2f97c884ff5..342e966bbf1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -20,6 +20,7 @@ import sys from contextlib import suppress +import jinja2.defaults import sphinx_autosummary_accessors # make sure the source version is preferred (#3567) @@ -104,6 +105,20 @@ """ autosummary_generate = True + + +def github_url(name): + url = "https://github.com/pydata/xarray/blob/{branch}/{path}" + branch = "master" + path = "/".join(name.split(".")) + + print(f"got: {name}, pointing to {url.format(branch=branch, path=path)}") + + return url.format(branch=branch, path=path) + + +jinja2.defaults.DEFAULT_FILTERS["github_url"] = github_url + autodoc_typehints = "none" napoleon_use_param = True From 9c4cf274ad3dd9802d6087f70a7083f004856885 Mon Sep 17 00:00:00 2001 From: Keewis Date: Thu, 13 Aug 2020 02:09:03 +0200 Subject: [PATCH 2/7] register the jinja filter using the setup function --- doc/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 342e966bbf1..c5aa9845ebf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -117,8 +117,6 @@ def github_url(name): return url.format(branch=branch, path=path) -jinja2.defaults.DEFAULT_FILTERS["github_url"] = github_url - autodoc_typehints = "none" napoleon_use_param = True @@ -376,3 +374,7 @@ def github_url(name): "dask": ("https://docs.dask.org/en/latest", None), "cftime": ("https://unidata.github.io/cftime", None), } + + +def setup(app): + jinja2.defaults.DEFAULT_FILTERS["github_url"] = github_url From f748f11f1ad227bcf80211589a148a71cc831c98 Mon Sep 17 00:00:00 2001 From: Keewis Date: Thu, 13 Aug 2020 02:24:33 +0200 Subject: [PATCH 3/7] fix the template --- doc/_templates/edit_on_github.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/_templates/edit_on_github.rst b/doc/_templates/edit_on_github.rst index 163d9d80c6a..56d5d2416c8 100644 --- a/doc/_templates/edit_on_github.rst +++ b/doc/_templates/edit_on_github.rst @@ -1,3 +1,3 @@ :github_url: {{ full_name | github_url }} -{% extends base.rst %} +{% extends "!autosummary/base.rst" %} From 6c58ccfcf9808219c0bb741ae64f145d733ee574 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 22 Sep 2020 00:27:46 +0200 Subject: [PATCH 4/7] use scanpydoc instead of a copy --- ci/requirements/doc.yml | 1 + doc/conf.py | 23 ++++++++--------------- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/ci/requirements/doc.yml b/ci/requirements/doc.yml index 5206b81518a..4170569f7b7 100644 --- a/ci/requirements/doc.yml +++ b/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 ../.. diff --git a/doc/conf.py b/doc/conf.py index bb4d22cc0b6..c22cd9a4703 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,11 +14,11 @@ import datetime import os +import pathlib import subprocess import sys from contextlib import suppress -import jinja2.defaults import sphinx_autosummary_accessors import xarray @@ -99,16 +99,13 @@ autosummary_generate = True - -def github_url(name): - url = "https://github.com/pydata/xarray/blob/{branch}/{path}" - branch = "master" - path = "/".join(name.split(".")) - - print(f"got: {name}, pointing to {url.format(branch=branch, path=path)}") - - return url.format(branch=branch, path=path) - +# 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" @@ -417,7 +414,3 @@ def github_url(name): "dask": ("https://docs.dask.org/en/latest", None), "cftime": ("https://unidata.github.io/cftime", None), } - - -def setup(app): - jinja2.defaults.DEFAULT_FILTERS["github_url"] = github_url From 087bf55f0b65c4ddf2814be1b9f89f65e5ff6d62 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 22 Sep 2020 01:56:18 +0200 Subject: [PATCH 5/7] fix the use of scanpydoc --- doc/_templates/autosummary/base.rst | 3 +++ doc/_templates/edit_on_github.rst | 3 --- doc/conf.py | 2 ++ 3 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 doc/_templates/autosummary/base.rst delete mode 100644 doc/_templates/edit_on_github.rst diff --git a/doc/_templates/autosummary/base.rst b/doc/_templates/autosummary/base.rst new file mode 100644 index 00000000000..d90a8de5a18 --- /dev/null +++ b/doc/_templates/autosummary/base.rst @@ -0,0 +1,3 @@ +:github_url: {{ fullname | github_url }} + +{% extends "!autosummary/base.rst" %} \ No newline at end of file diff --git a/doc/_templates/edit_on_github.rst b/doc/_templates/edit_on_github.rst deleted file mode 100644 index 56d5d2416c8..00000000000 --- a/doc/_templates/edit_on_github.rst +++ /dev/null @@ -1,3 +0,0 @@ -:github_url: {{ full_name | github_url }} - -{% extends "!autosummary/base.rst" %} diff --git a/doc/conf.py b/doc/conf.py index c22cd9a4703..af873606eaf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -79,6 +79,7 @@ "IPython.sphinxext.ipython_console_highlighting", "nbsphinx", "sphinx_autosummary_accessors", + "scanpydoc.rtd_github_links", ] extlinks = { @@ -105,6 +106,7 @@ "github_user": "pydata", "github_repo": "xarray", "github_version": "master", + "conf_py_path": "/doc/", } autodoc_typehints = "none" From 31621a9515ac5aadf2432f9b8e31996591f38057 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 22 Sep 2020 02:24:52 +0200 Subject: [PATCH 6/7] escape underscores in github urls --- doc/_templates/autosummary/base.rst | 2 +- doc/conf.py | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/doc/_templates/autosummary/base.rst b/doc/_templates/autosummary/base.rst index d90a8de5a18..e6726a71d7c 100644 --- a/doc/_templates/autosummary/base.rst +++ b/doc/_templates/autosummary/base.rst @@ -1,3 +1,3 @@ -:github_url: {{ fullname | github_url }} +:github_url: {{ fullname | github_url | escape_underscores }} {% extends "!autosummary/base.rst" %} \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py index af873606eaf..e43bb241b74 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -20,6 +20,7 @@ from contextlib import suppress import sphinx_autosummary_accessors +from jinja2.defaults import DEFAULT_FILTERS import xarray @@ -416,3 +417,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 From 9472bd19a4f2311d298e62ade6d890e6a95f64e6 Mon Sep 17 00:00:00 2001 From: Keewis Date: Fri, 25 Sep 2020 18:56:38 +0200 Subject: [PATCH 7/7] don't override conf_py_path, RTD correctly detects that --- doc/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index e43bb241b74..3db0b356263 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -107,7 +107,6 @@ "github_user": "pydata", "github_repo": "xarray", "github_version": "master", - "conf_py_path": "/doc/", } autodoc_typehints = "none"