From d637557f5a5396c9cad93de4fd9454792795f44a Mon Sep 17 00:00:00 2001 From: Marc Bonnici Date: Thu, 21 Jun 2018 14:56:09 +0100 Subject: [PATCH] doc: Update links to have more useful display text --- .../developer_reference/execution_model.rst | 4 ++-- .../developer_reference/writing_plugins.rst | 4 ++-- .../how_tos/adding_plugins.rst | 14 ++++++++------ doc/source/glossary.rst | 5 +++-- doc/source/instrument_method_map.template | 4 ++-- doc/source/user_information/installation.rst | 2 +- doc/source/user_information/user_guide.rst | 2 +- 7 files changed, 19 insertions(+), 16 deletions(-) diff --git a/doc/source/developer_information/developer_reference/execution_model.rst b/doc/source/developer_information/developer_reference/execution_model.rst index ab3e28c5..0b847cb6 100644 --- a/doc/source/developer_information/developer_reference/execution_model.rst +++ b/doc/source/developer_information/developer_reference/execution_model.rst @@ -120,8 +120,8 @@ for the run. Priority can then be specified by adding ``extremely_fast``, ``very_fast``, ``fast`` , ``slow``, ``very_slow`` or ``extremely_slow`` :ref:`decorators ` to the method definitions. -The full list of method names and the signals they map to may be viewed -:ref:`here `. +The full list of method names and the signals they map to may be seen at the +:ref:`instrument method map `. Signal dispatching mechanism may also be used directly, for example to dynamically register callbacks at runtime or allow plugins other than diff --git a/doc/source/developer_information/developer_reference/writing_plugins.rst b/doc/source/developer_information/developer_reference/writing_plugins.rst index 2d980b4d..0774ed5d 100644 --- a/doc/source/developer_information/developer_reference/writing_plugins.rst +++ b/doc/source/developer_information/developer_reference/writing_plugins.rst @@ -859,8 +859,8 @@ Each method in ``Instrument`` must take two arguments, which are ``self`` and ``context``. Supported methods and their corresponding signals can be found in the :ref:`Signals Documentation `. To make implementations easier and common, the basic steps to add new instrument is -similar to the steps to add new workload and an example can be found -:ref:`here `. +similar to the steps to add new workload and an example can be found in the +:ref:`How To ` section. .. _instrument-api: diff --git a/doc/source/developer_information/how_tos/adding_plugins.rst b/doc/source/developer_information/how_tos/adding_plugins.rst index b47407f2..6a9f6d05 100644 --- a/doc/source/developer_information/how_tos/adding_plugins.rst +++ b/doc/source/developer_information/how_tos/adding_plugins.rst @@ -49,7 +49,8 @@ on using the create workload command see ``wa create workload -h`` The first thing to decide is the type of workload you want to create depending on the OS you will be using and the aim of the workload. The are currently 6 -available workload types to choose as detailed :ref:`here`. +available workload types to choose as detailed in the +:ref:`Developer Reference `. Once you have decided what type of workload you wish to choose this can be specified with ``-k `` followed by the workload name. This @@ -383,8 +384,8 @@ The main difference between the two is that this workload will subclass Adding an Instrument Example ============================= This is an example of how we would create a instrument which will trace device -errors using a custom "trace" binary file. For more detailed information please see -:ref:`here `. The first thing to do is to subclass +errors using a custom "trace" binary file. For more detailed information please see the +:ref:`Instrument Reference `. The first thing to do is to subclass :class:`Instrument`, overwrite the variable name with what we want our instrument to be called and locate our binary for our instrument. @@ -400,8 +401,8 @@ to be called and locate our binary for our instrument. self.binary_file = os.path.join(os.path.dirname(__file__), self.binary_name) self.trace_on_target = None -We then declare and implement the required methods as detailed -:ref:`here `. For the ``initialize`` method, we want to install +We then declare and implement the required methods as detailed in the +:ref:`Instrument API `. For the ``initialize`` method, we want to install the executable file to the target so we can use the target's ``install`` method which will try to copy the file to a location on the device that supports execution, change the file mode appropriately and return the @@ -414,7 +415,8 @@ Then we implemented the start method, which will simply run the file to start tracing. Supposing that the call to this binary requires some overhead to begin collecting errors we might want to decorate the method with the ``@slow`` decorator to try and reduce the impact on other running instruments. For more -information on prioritization please see :ref:`here `. :: +information on prioritization please see the +:ref:`Developer Reference `. :: @slow def start(self, context): diff --git a/doc/source/glossary.rst b/doc/source/glossary.rst index ef23a95b..b6a58d9c 100644 --- a/doc/source/glossary.rst +++ b/doc/source/glossary.rst @@ -7,7 +7,7 @@ Glossary An agenda specifies what is to be done during a Workload Automation run. This includes which workloads will be run, with what configuration and which augmentations will be enabled, etc. (For more information - please see :ref:`here `.) + please see the :ref:`Agenda Reference `.) Alias An alias associated with a workload or a parameter. In case of @@ -38,7 +38,8 @@ Glossary An artifact is something that was been generated as part of the run for example a file containing output or meta data in the form of log files. WA supports multiple "kinds" of artifacts and will handle them - accordingly, for more information please see :ref:`here `. + accordingly, for more information please see the + :ref:`Developer Reference `. Classifier An arbitrary key-value pair that may associated with a :term:`job`\ , a diff --git a/doc/source/instrument_method_map.template b/doc/source/instrument_method_map.template index 9aa45781..4029c015 100644 --- a/doc/source/instrument_method_map.template +++ b/doc/source/instrument_method_map.template @@ -7,8 +7,8 @@ Instrument methods get automatically hooked up to signals based on their names. Mostly, the method name corresponds to the name of the signal, however there are a few convenience aliases defined (listed first) to make easier to relate instrumentation code to the workload execution model. For an overview on when -these signals are dispatched during execution please see -:ref:`here `. +these signals are dispatched during execution please see the +:ref:`Developer Reference `. $signal_names diff --git a/doc/source/user_information/installation.rst b/doc/source/user_information/installation.rst index da776a09..bd11f773 100644 --- a/doc/source/user_information/installation.rst +++ b/doc/source/user_information/installation.rst @@ -261,7 +261,7 @@ surface. For these, an interaction session needs to be recorded so that it can be played back by WA. These recordings are device-specific, so they would need to be done for each device you're planning to use. The tool for doing is ``revent`` and it is packaged with WA. You can find instructions on how to use -it :ref:`here `. +it in the :ref:`How To ` section. This is the list of workloads that rely on such recordings: diff --git a/doc/source/user_information/user_guide.rst b/doc/source/user_information/user_guide.rst index 596ebc26..08cf9ce8 100644 --- a/doc/source/user_information/user_guide.rst +++ b/doc/source/user_information/user_guide.rst @@ -44,7 +44,7 @@ dependencies. Alternatively we provide a Dockerfile that which can be used to create a Docker image for running WA along with its dependencies. More information can be found -:ref:`here `. +in the :ref:`Installation ` section. (Optional) Verify installation -------------------------------