From 6e00a4ff2a3adab8b21d70a2e8ae96e6fe1b5d2c Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sat, 7 Mar 2020 17:17:08 -0700 Subject: [PATCH 1/8] tentative fix --- .../sphinx/source/_templates/breadcrumbs.html | 26 ++++++ docs/sphinx/source/conf.py | 90 ++++++++++++++++++- 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/source/_templates/breadcrumbs.html diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html new file mode 100644 index 00000000..80201d1f --- /dev/null +++ b/docs/sphinx/source/_templates/breadcrumbs.html @@ -0,0 +1,26 @@ +{# + +Modify the "Edit on Github" links to handle auto-generated pages in the +API reference listings. The GH links that sphinx generates by default make +the assumption that an HTML file comes from an RST file with the same +filepath, which isn't the case for autogenerated files. + +We need to generate the target URL differently based on the type +of page. We use the built-in `pagename` variable to determine what +kind of page this is. `pagename` is the path at the end of the +URL, without the extension. For instance, +https://rdtools.rtfd.io/en/latest/generated/rdtools.soiling.soiling_srr.html +will have pagename = "generated/rdtools.soiling.soiling_srr.html". + +Note: make_github_url is defined in conf.py +#} + +{% extends "!breadcrumbs.html" %} +{% block breadcrumbs_aside %} +
  • + {# Get the appropriate GH link based on this page's name: #} + {% set target_url = make_github_url(pagename) %} + {# Create the HTML element with our custom GH link: #} + View on Github +
    • +{% endblock %} \ No newline at end of file diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 7037d373..beb1f19e 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -15,6 +15,7 @@ # prefer local rdtools folder to one installed in a venv or site-packages: import os import sys +import inspect sys.path.insert(0, os.path.abspath('../../..')) @@ -84,4 +85,91 @@ master_doc = 'index' # A workaround for the responsive tables always having annoying scrollbars. def setup(app): - app.add_stylesheet("no_scrollbars.css") \ No newline at end of file + app.add_stylesheet("no_scrollbars.css") + + +# %% helper functions for intelligent "View on Github" linking +# based on +# https://gist.github.com/flying-sheep/b65875c0ce965fbdd1d9e5d0b9851ef1 + +def get_obj_module(qualname): + """ + Get a module/class/attribute and its original module by qualname. + Useful for looking up the original location when a function is imported + into an __init__.py + + Examples + -------- + >>> func, mod = get_obj_module("rdtools.degradation_ols") + >>> mod.__name__ + 'rdtools.degradation' + """ + modname = qualname + classname = None + attrname = None + while modname not in sys.modules: + attrname = classname + modname, classname = modname.rsplit('.', 1) + + # retrieve object and find original module name + if classname: + cls = getattr(sys.modules[modname], classname) + modname = cls.__module__ + obj = getattr(cls, attrname) if attrname else cls + else: + obj = None + + return obj, sys.modules[modname] + + +def get_linenos(obj): + """Get an object’s line numbers in its source code file""" + try: + lines, start = inspect.getsourcelines(obj) + except TypeError: # obj is an attribute or None + return None, None + else: + return start, start + len(lines) - 1 + + +def make_github_url(pagename): + """ + Generate the appropriate GH link for a given docs page. This function + is intended for use in sphinx template files. + The target URL is built differently based on the type of page. Sphinx + provides templates with a built-in `pagename` variable that is the path + at the end of the URL, without the extension. For instance, + https://rdtools.rtfd.io/en/latest/generated/rdtools.soiling.soiling_srr.html + will have pagename = "generated/rdtools.soiling.soiling_srr.html". + """ + + URL_BASE = "https://github.com/nrel/rdtools/blob/master/" + + # is it an API autogen page? + if "generated" in pagename: + # pagename looks like "generated/rdtools.degradation.degradation_ols" + qualname = pagename.split("/")[-1] + obj, module = get_obj_module(qualname) + path = module.__name__.replace(".", "/") + ".py" + target_url = URL_BASE + path + # add line numbers if possible: + start, end = get_linenos(obj) + if start and end: + target_url += '#L{}-L{}'.format(start, end) + + # is it the example notebook? + elif pagename == "example": + target_url = URL_BASE + "/docs/degradation_and_soiling_example.ipynb" + + # Just a normal source RST page + else: + target_url = URL_BASE + "docs/sphinx/source/" + pagename + ".rst" + + return target_url + + +# variables to pass into the HTML templating engine; these are accessible from +# _templates/breadcrumbs.html +html_context = { + 'make_github_url': make_github_url, +} \ No newline at end of file From d188b7dc10845436c144b444849050d40991661e Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sat, 7 Mar 2020 17:18:31 -0700 Subject: [PATCH 2/8] fix slash --- docs/sphinx/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index beb1f19e..7936c19b 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -159,7 +159,7 @@ def make_github_url(pagename): # is it the example notebook? elif pagename == "example": - target_url = URL_BASE + "/docs/degradation_and_soiling_example.ipynb" + target_url = URL_BASE + "docs/degradation_and_soiling_example.ipynb" # Just a normal source RST page else: From 721c968592c417ebed2d14eee740ac315c28f961 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 17 Mar 2020 15:50:43 -0600 Subject: [PATCH 3/8] include branch logic based on RTD version --- docs/sphinx/source/conf.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 7936c19b..29797be5 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -140,10 +140,17 @@ def make_github_url(pagename): provides templates with a built-in `pagename` variable that is the path at the end of the URL, without the extension. For instance, https://rdtools.rtfd.io/en/latest/generated/rdtools.soiling.soiling_srr.html - will have pagename = "generated/rdtools.soiling.soiling_srr.html". + will have pagename = "generated/rdtools.soiling.soiling_srr". """ - URL_BASE = "https://github.com/nrel/rdtools/blob/master/" + # RTD automatically sets READTHEDOCS_VERSION to the version being built. + if os.environ.get('READTHEDOCS_VERSION', None) == 'stable': + branch = 'master' + else: + # if 'latest', a PR build, or unset (e.g. building locally) + branch = 'development' + + URL_BASE = "https://github.com/nrel/rdtools/blob/{}/".format(branch) # is it an API autogen page? if "generated" in pagename: From 197d31c6902b8bfb8c12289d2966f3f7343a1e66 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 17 Mar 2020 16:04:49 -0600 Subject: [PATCH 4/8] small improvement --- docs/sphinx/source/_templates/breadcrumbs.html | 2 +- docs/sphinx/source/conf.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html index 80201d1f..05427b4f 100644 --- a/docs/sphinx/source/_templates/breadcrumbs.html +++ b/docs/sphinx/source/_templates/breadcrumbs.html @@ -10,7 +10,7 @@ kind of page this is. `pagename` is the path at the end of the URL, without the extension. For instance, https://rdtools.rtfd.io/en/latest/generated/rdtools.soiling.soiling_srr.html -will have pagename = "generated/rdtools.soiling.soiling_srr.html". +will have pagename = "generated/rdtools.soiling.soiling_srr". Note: make_github_url is defined in conf.py #} diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 29797be5..fe4a67be 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -153,7 +153,7 @@ def make_github_url(pagename): URL_BASE = "https://github.com/nrel/rdtools/blob/{}/".format(branch) # is it an API autogen page? - if "generated" in pagename: + if pagename.startswith("generated/"): # pagename looks like "generated/rdtools.degradation.degradation_ols" qualname = pagename.split("/")[-1] obj, module = get_obj_module(qualname) From c289600e3fee45e0664bcc72b9d8c69b47c4d8f0 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 20 Mar 2020 13:24:58 -0600 Subject: [PATCH 5/8] omit GH link element if not building development or master --- docs/sphinx/source/_templates/breadcrumbs.html | 16 ++++++++++------ docs/sphinx/source/conf.py | 17 ++++++++++++----- 2 files changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html index 05427b4f..a18d2a57 100644 --- a/docs/sphinx/source/_templates/breadcrumbs.html +++ b/docs/sphinx/source/_templates/breadcrumbs.html @@ -17,10 +17,14 @@ {% extends "!breadcrumbs.html" %} {% block breadcrumbs_aside %} -
  • - {# Get the appropriate GH link based on this page's name: #} - {% set target_url = make_github_url(pagename) %} - {# Create the HTML element with our custom GH link: #} - View on Github -
    • + {# Get the appropriate GH link based on this page's name: #} + {% set target_url = make_github_url(pagename) %} + + {# Create the HTML element with our custom GH link, unless it couldn't + be determined. Note that None is lowercase in templates. #} + {% if target_url is not none %} +
  • + View on Github +
    • + {% endif %} {% endblock %} \ No newline at end of file diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index fe4a67be..b98d2440 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -141,14 +141,21 @@ def make_github_url(pagename): at the end of the URL, without the extension. For instance, https://rdtools.rtfd.io/en/latest/generated/rdtools.soiling.soiling_srr.html will have pagename = "generated/rdtools.soiling.soiling_srr". + + Returns None if not building development or master. """ # RTD automatically sets READTHEDOCS_VERSION to the version being built. - if os.environ.get('READTHEDOCS_VERSION', None) == 'stable': - branch = 'master' - else: - # if 'latest', a PR build, or unset (e.g. building locally) - branch = 'development' + rtd_version = os.environ.get('READTHEDOCS_VERSION', None) + version_map = { + 'stable': 'master', + 'latest': 'development', + } + try: + branch = version_map[rtd_version] + except KeyError: + # for other builds (PRs, local builds etc), it's unclear where to link + return None URL_BASE = "https://github.com/nrel/rdtools/blob/{}/".format(branch) From 5320c626296c87b0cf9d0c2f813eb0cad5f7f6f3 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sat, 2 May 2020 13:05:18 -0600 Subject: [PATCH 6/8] change github link text to reflect the destination branch --- docs/sphinx/source/_templates/breadcrumbs.html | 6 ++++-- docs/sphinx/source/conf.py | 7 ++++++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html index a18d2a57..0962db1d 100644 --- a/docs/sphinx/source/_templates/breadcrumbs.html +++ b/docs/sphinx/source/_templates/breadcrumbs.html @@ -18,13 +18,15 @@ {% extends "!breadcrumbs.html" %} {% block breadcrumbs_aside %} {# Get the appropriate GH link based on this page's name: #} - {% set target_url = make_github_url(pagename) %} + {% set link_info = make_github_url(pagename) %} {# Create the HTML element with our custom GH link, unless it couldn't be determined. Note that None is lowercase in templates. #} {% if target_url is not none %}
  • - View on Github + + {{ link_info['text'] }} +
    • {% endif %} {% endblock %} \ No newline at end of file diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index b98d2440..71b2c3d5 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -179,7 +179,12 @@ def make_github_url(pagename): else: target_url = URL_BASE + "docs/sphinx/source/" + pagename + ".rst" - return target_url + display_text = "View on github/" + branch + link_info = { + 'url': target_url, + 'text': display_text + } + return link_info # variables to pass into the HTML templating engine; these are accessible from From 5d28604db88e9dd1a4b3ebc61edb07a392bb866a Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sat, 2 May 2020 13:06:30 -0600 Subject: [PATCH 7/8] link changelog page to changelog GH folder instead of the template rst file --- docs/sphinx/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 71b2c3d5..87e99633 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -175,6 +175,10 @@ def make_github_url(pagename): elif pagename == "example": target_url = URL_BASE + "docs/degradation_and_soiling_example.ipynb" + # is the the changelog page? + elif pagename == "changelog": + target_url = URL_BASE + "docs/sphinx/source/changelog" + # Just a normal source RST page else: target_url = URL_BASE + "docs/sphinx/source/" + pagename + ".rst" From 7d907ba68c8df9b44bb2a3e04c0805eed113c57c Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Sat, 2 May 2020 13:09:47 -0600 Subject: [PATCH 8/8] bugfix --- docs/sphinx/source/_templates/breadcrumbs.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/source/_templates/breadcrumbs.html b/docs/sphinx/source/_templates/breadcrumbs.html index 0962db1d..a6444283 100644 --- a/docs/sphinx/source/_templates/breadcrumbs.html +++ b/docs/sphinx/source/_templates/breadcrumbs.html @@ -22,7 +22,7 @@ {# Create the HTML element with our custom GH link, unless it couldn't be determined. Note that None is lowercase in templates. #} - {% if target_url is not none %} + {% if link_info is not none %}
  • {{ link_info['text'] }}