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/conf.py

@@ -37,7 +37,7 @@ if "RELEASE" in os.environ:
 sys.path.insert(0, os.path.join(os.path.abspath('.'), 'extensions'))
 extensions = [
    'breathe', 'sphinx.ext.graphviz', 'sphinx.ext.extlinks',
-   'kerneldoc', 'eager_only', 'html_redirects',
+   'kerneldoc', 'eager_only', 'html_redirects', 'link_roles',
    'sphinx_tabs.tabs'
 ]
 

doc/developer-guides/contribute_guidelines.rst

@@ -20,7 +20,7 @@ software continues to be available under the terms that the author
 desired.
 
 Project ACRN uses a BSD-3-Clause license, as found in the
-`LICENSE <https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE>`__
+:acrn_file:`LICENSE <LICENSE>`
 in the project's GitHub repo.
 
 A license tells you what rights you have as a developer, as provided by
@@ -221,14 +221,12 @@ following exceptions:
   8-column wide.
 
 You can use *checkpatch* from Linux kernel to check the compliance. ACRN
-maintains a `checkpatch conf`_ which customizes the script to stop warning on
+maintains a :acrn_file:`.checkpatch.conf <.checkpatch.conf>` file
+that customizes the script to stop warnings on
 the exceptions above. Invoke *checkpatch* with the root of ``acrn-hypervisor``
 repository as the current working directory to make the configurations
 effective.
 
-.. _checkpatch conf:
-   https://github.com/projectacrn/acrn-hypervisor/blob/master/.checkpatch.conf
-
 .. _Contribution workflow:
 
 Contribution Workflow

doc/developer-guides/doc_guidelines.rst

@@ -297,6 +297,17 @@ markup (double backticks) to indicate a ``filename``.
 
 Don't use items within a single backtick, for example ```word```.
 
+For references to files that are in the ACRN Hypervisor GitHub tree, a special
+role can be used that creates a hyperlink to that file. For example a
+GitHub link to the reST file used to create this document can be generated
+using ``:acrn_file:`doc/developer-guides/doc_guidelines.rst``` that will show
+up as :acrn_file:`doc/developer-guides/doc_guidelines.rst`, a link to
+the “blob” file in the GitHub repo as displayed by GitHub. There’s also an
+``:acrn_raw:`doc/developer-guides/doc_guidelines.rst``` role that will link
+to the “raw” uninterpreted file,
+:acrn_raw:`doc/developer-guides/doc_guidelines.rst` file. (Click
+on these links to see the difference.)
+
 .. _internal-linking:
 
 Internal Cross-Reference Linking

doc/developer-guides/hld/virtio-net.rst

@@ -426,10 +426,11 @@ our case, we use systemd to automatically create the network by default.
 You can check the files with prefix 50- in the Service VM
 ``/usr/lib/systemd/network/``:
 
-- `50-acrn.netdev <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/acrn.netdev>`__
-- `50-acrn.network <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/acrn.network>`__
-- `50-tap0.netdev <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/tap0.netdev>`__
-- `50-eth.network <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/misc/acrnbridge/eth.network>`__
+- :acrn_raw:`50-acrn.netdev <misc/acrnbridge/acrn.netdev>`
+- :acrn_raw:`50-acrn.netdev <misc/acrnbridge/acrn.netdev>`
+- :acrn_raw:`50-acrn.network <misc/acrnbridge/acrn.network>`
+- :acrn_raw:`50-tap0.netdev <misc/acrnbridge/tap0.netdev>`
+- :acrn_raw:`50-eth.network <misc/acrnbridge/eth.network>`
 
 When the Service VM is started, run ``ifconfig`` to show the devices created by
 this systemd configuration:

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

doc/index.rst

@@ -86,7 +86,4 @@ license.
    glossary
    genindex
 
-.. _BSD 3-clause license:
-   https://github.com/projectacrn/acrn-hypervisor/blob/master/LICENSE
-
 .. _Project ACRN GitHub repo: https://github.com/projectacrn

doc/introduction/index.rst

@@ -93,10 +93,10 @@ above, i.e. the *logical partitioning*, *sharing*, and *hybrid* modes. They
 further specify the number of VMs that can be run, their attributes and the
 resources they have access to, either shared with other VMs or exclusively.
 
-The predefined scenarios are in the `misc/vm_configs/scenarios
-<https://github.com/projectacrn/acrn-hypervisor/tree/master/misc/vm_configs/scenarios>`_
-folder in the source code. XML examples for some platforms can also be found under
-`misc/vm_configs/xmls/config-xmls <https://github.com/projectacrn/acrn-hypervisor/tree/master/misc/vm_configs/xmls/config-xmls/>`_.
+The predefined scenarios are in the
+:acrn_file:`misc/vm_configs/scenarios` folder
+in the source code. XML examples for some platforms can also be found under
+:acrn_file:`misc/vm_configs/xmls/config-xmls`.
 
 The :ref:`acrn_configuration_tool` tutorial explains how to use the ACRN
 Configuration tool to create your own scenario or modify an existing one.

doc/tutorials/setup_openstack_libvirt.rst

@@ -223,11 +223,12 @@ Use DevStack to install OpenStack. Refer to the `DevStack instructions <https://
 
      $ git clone https://opendev.org/openstack/devstack.git -b stable/train
 
-2. Go into the ``devstack`` directory and apply an ACRN patch::
+2. Go into the ``devstack`` directory, download an ACRN patch from
+   :acrn_raw:`doc/tutorials/0001-devstack-installation-for-acrn.patch`,
+   and apply it ::
 
       $ cd devstack
-      $ curl https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/tutorials/0001-devstack-installation-for-acrn.patch \
-        | git apply
+      $ git apply 0001-devstack-installation-for-acrn.patch
 
 3. Edit ``lib/nova_plugins/hypervisor-libvirt``:
 

misc/acrn-manager/README.rst

@@ -54,8 +54,8 @@ container::
 
    # acrnctl add launch_uos.sh -C
 
-.. note:: You can download an `example launch_uos.sh script
-   <https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/devicemodel/samples/nuc/launch_uos.sh>`_
+.. note:: You can download an :acrn_raw:`example launch_uos.sh script
+   <devicemodel/samples/nuc/launch_uos.sh>`
    that supports the ``-C``  (``run_container`` function) option. 
 
 Note that the launch script must only launch one User VM instance.