doc: add extension to create files and raw links

Links to files in the GitHub repo's master branch should be to the files
within the branch being generated.  For example, in the v2.1
documentation, links should be to the v2.1 branch contents.  (Previously
links were being made to the master branch in all our archived content.)
This creates a problem when we want to remove an obsolete file in the
master branch but can't because older documentaiton incorrectly depends
on it.

This new extension defines a :acrn_file: and :acrn_raw: role that will
create links to the given file within the current commit branch.

This PR also replaces docs with hard-coded links to files in the master
branch with uses of these new roles to create links to files.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

doc/extensions/eager_only.py

@@ -30,7 +30,7 @@ class EagerOnly(sphinx.directives.other.Only):
         # Evaluate the condition eagerly, and if false return no nodes right away
         env = self.state.document.settings.env
         env.app.builder.tags.add('TRUE')
-        #print(repr(self.arguments[0]))
+
         if not env.app.builder.tags.eval_condition(self.arguments[0]):
             return []
 
@@ -43,3 +43,13 @@ class EagerOnly(sphinx.directives.other.Only):
 
 def setup(app):
     directives.register_directive('only', EagerOnly)
+
+    # The tags.add call above is setting tags.tags['TRUE'] = True.
+    # The operation is idempotent and will have taken effect before
+    # the next eval_condition() which may rely on it so this is thread
+    # safe both for read and writes (all other operations are local to
+    # the local nodes variable).
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+        }

doc/extensions/link_roles.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2019 Intel Corporation
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# based on http://protips.readthedocs.io/link-roles.html
+
+from __future__ import print_function
+from __future__ import unicode_literals
+import re
+import os
+import os.path
+from os import path
+import subprocess
+from docutils import nodes
+
+
+def run_cmd_get_output(cmd):
+    try:
+        with open(os.devnull, 'w') as devnull:
+            output = subprocess.check_output(cmd, stderr=devnull, shell=True).strip()
+    except subprocess.CalledProcessError as e:
+        output = e.output.decode('ascii')
+
+    return output
+
+def get_github_rev():
+    tag = run_cmd_get_output('git describe --exact-match')
+    if tag:
+        return tag.decode("utf-8")
+    else:
+        return 'master'
+
+
+def setup(app):
+    rev = get_github_rev()
+
+    baseurl = 'https://github.com/projectacrn/acrn-hypervisor'
+
+    app.add_role('acrn_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
+    app.add_role('acrn_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
+
+    # The role just creates new nodes based on information in the
+    # arguments; its behavior doesn't depend on any other documents.
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+
+def autolink(pattern):
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        m = re.search(r'(.*)\s*<(.*)>', text)
+        if m:
+            link_text = m.group(1)
+            link = m.group(2)
+        else:
+            link_text = text
+            link = text
+        url = pattern % (link,)
+        node = nodes.reference(rawtext, link_text, refuri=url, **options)
+        return [node], []
+    return role