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/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: