docs: fix link to stable versions

The "scm_raw_web" and "scm_web" macros are used in the documentation to create
links to specific versions of the documents. It's useful to point to the right
version of the examples for instance.

There is a special "stable" version in readthedocs that points to the highest
release, generated links to that version are wrongly pointing to a non existing
"satble" release. This commit fixes that logic by getting the highest release
by using the Github API when building documents for the stable release.

docs-requirements.txt

@@ -1,6 +1,7 @@
 sphinx~=2.4
 sphinx-rtd-theme~=0.4
 sphinx-autodoc-typehints~=1.10.2
+semver~=2.9
 
 # Required by ext packages
 opentracing~=2.2.0

docs/conf.py

@@ -10,11 +10,39 @@
 # 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 functools
+import json
 import os
 import sys
 from os import listdir
 from os.path import isdir, join
 
+import requests
+
+import semver
+
+
+def get_latest_tag(repo):
+    # TODO: Use releases/latest once we have a non-prelease
+    # https://developer.github.com/v3/repos/releases/#get-the-latest-release
+    names = []
+    url = "https://api.github.com/repos/" + repo + "/tags"
+
+    result = requests.get(url)
+
+    if result.status_code != 200:
+        print("Error getting latest tag: " + result.text)
+        return None
+
+    for req in result.json():
+        n = req["name"][1:]  # remove leading "v"
+        if semver.VersionInfo.isvalid(n):  # ignore non semver tags
+            names.append(n)
+
+    k = functools.cmp_to_key(semver.compare)
+    return "v" + max(names, key=k)
+
+
 source_dirs = [
     os.path.abspath("../opentelemetry-api/src/"),
     os.path.abspath("../opentelemetry-sdk/src/"),
@@ -109,14 +137,21 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
+REPO = "open-telemetry/opentelemetry-python"
+
 # Support external links to specific versions of the files in the Github repo
-branch = os.environ.get("READTHEDOCS_VERSION")
-if branch is None or branch == "latest":
-    branch = "master"
 
-REPO = "open-telemetry/opentelemetry-python/"
-scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch
-scm_web = "https://github.com/" + REPO + "blob/" + branch
+branch = "master"  # by default point to master
+
+if os.environ.get("READTHEDOCS") == "True":
+    version = os.environ.get("READTHEDOCS_VERSION")
+    if version == "latest":
+        branch = "master"
+    elif version == "stable":
+        branch = get_latest_tag(REPO) or branch
+
+scm_raw_web = "https://raw.githubusercontent.com/{}/{}".format(REPO, branch)
+scm_web = "https://github.com/{}/blob/{}".format(REPO, branch)
 
 # Store variables in the epilogue so they are globally available.
 rst_epilog = """

tox.ini

@@ -202,6 +202,7 @@ deps =
   sphinx
   sphinx-rtd-theme
   sphinx-autodoc-typehints
+  semver
   # Required by ext packages
   opentracing
   Deprecated