docs: fix "link to translation" being broken

The translation link would link a specifc commit hash instead of
the release name.

docs/link-roles.py

@@ -6,6 +6,7 @@ import re
 import os
 from docutils import nodes
 from local_util import run_cmd_get_output
+from sphinx.transforms.post_transforms import SphinxPostTransform
 
 
 def get_github_rev():
@@ -34,17 +35,42 @@ def setup(app):
     app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev)))
 
     # link to the current documentation file in specific language version
-    on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-    if on_rtd:
-        # provide RTD specific commit identification to be included in the link
-        tag_rev = 'latest'
-        if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
-            tag_rev = rev
-    else:
-        # if not on the RTD then provide generic identification
-        tag_rev = run_cmd_get_output('git describe --always')
+    app.add_role('link_to_translation', link_to_translation)
+    app.add_node(translation_link)
+    app.add_post_transform(TranslationLinkNodeTransform)
 
-    app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
+
+class translation_link(nodes.Element):
+    """Node for "link_to_translation" role."""
+
+
+# Linking to translation is done at the "writing" stage to avoid issues with the info being cached between builders
+def link_to_translation(name, rawtext, text, lineno, inliner, options={}, content=[]):
+    node = translation_link()
+    node['expr'] = (rawtext, text, options)
+    return [node], []
+
+
+class TranslationLinkNodeTransform(SphinxPostTransform):
+    # Transform needs to happen early to ensure the new reference node is also transformed
+    default_priority = 0
+
+    def run(self, **kwargs):
+
+        # Only output relative links if building HTML
+        for node in self.document.traverse(translation_link):
+            if 'html' in self.app.builder.name:
+                rawtext, text, options = node['expr']
+                (language, link_text) = text.split(':')
+                env = self.document.settings.env
+                docname = env.docname
+                doc_path = env.doc2path(docname, None, None)
+                return_path = '../' * doc_path.count('/')  # path back to the root from 'docname'
+                # then take off 2 more paths for language/release/ and build the new URL
+                url = '{}.html'.format(os.path.join(return_path, '../..', language, env.config.release, docname))
+                node.replace_self(nodes.reference(rawtext, link_text, refuri=url, **options))
+            else:
+                node.replace_self([])
 
 
 def autolink(pattern):