diff --git a/doc/conf.py b/doc/conf.py index 14a21f270..e00ec5c92 100644 --- a/doc/conf.py +++ b/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' ] diff --git a/doc/developer-guides/contribute_guidelines.rst b/doc/developer-guides/contribute_guidelines.rst index 7088f3bc7..6c6b6e235 100644 --- a/doc/developer-guides/contribute_guidelines.rst +++ b/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 `__ +:acrn_file:`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 diff --git a/doc/developer-guides/doc_guidelines.rst b/doc/developer-guides/doc_guidelines.rst index 275c6fcd5..ab92e5df7 100644 --- a/doc/developer-guides/doc_guidelines.rst +++ b/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 diff --git a/doc/developer-guides/hld/virtio-net.rst b/doc/developer-guides/hld/virtio-net.rst index 72dea16f3..1a286ea76 100644 --- a/doc/developer-guides/hld/virtio-net.rst +++ b/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 `__ -- `50-acrn.network `__ -- `50-tap0.netdev `__ -- `50-eth.network `__ +- :acrn_raw:`50-acrn.netdev ` +- :acrn_raw:`50-acrn.netdev ` +- :acrn_raw:`50-acrn.network ` +- :acrn_raw:`50-tap0.netdev ` +- :acrn_raw:`50-eth.network ` When the Service VM is started, run ``ifconfig`` to show the devices created by this systemd configuration: diff --git a/doc/extensions/eager_only.py b/doc/extensions/eager_only.py index 82766c2e6..155fddd57 100644 --- a/doc/extensions/eager_only.py +++ b/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, + } diff --git a/doc/extensions/link_roles.py b/doc/extensions/link_roles.py new file mode 100644 index 000000000..570907060 --- /dev/null +++ b/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 diff --git a/doc/index.rst b/doc/index.rst index b6819e03c..ce99b5e4b 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst index 3f72a01ba..0878a19f7 100644 --- a/doc/introduction/index.rst +++ b/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 -`_ -folder in the source code. XML examples for some platforms can also be found under -`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. diff --git a/doc/tutorials/setup_openstack_libvirt.rst b/doc/tutorials/setup_openstack_libvirt.rst index e4622b852..752b507fb 100644 --- a/doc/tutorials/setup_openstack_libvirt.rst +++ b/doc/tutorials/setup_openstack_libvirt.rst @@ -223,11 +223,12 @@ Use DevStack to install OpenStack. Refer to the `DevStack instructions `_ +.. note:: You can download an :acrn_raw:`example launch_uos.sh script + ` that supports the ``-C`` (``run_container`` function) option. Note that the launch script must only launch one User VM instance.