doc: fix inline interpreted text without a role

sphinx became stricter when handling interpreted text without a role,
e.g. "`foo`" since [1], see [2]. This results in errors such as:

  sphinx.errors.SphinxError: cannot determine default role!

In the past, heuristics were used to determine how
to format the text (inline code, italic, ..).

In labgrid, interpreted text without a role is used inconsistently. Most
times it was actually meant to be either inline code ("``foo``"), italic
text or links to docs sections or class definitions.
Fix all such occurrences with explicit variants that actually make sense
in their respective contexts.

[1] sphinx-doc/sphinx@114093c
[2] sphinx-doc/sphinx#13904

Signed-off-by: Bastian Krause <bst@pengutronix.de>

Author: Bastian-Krause

doc/configuration.rst

@@ -637,9 +637,9 @@ USB based gpiochips.
        '@ID_SERIAL_SHORT': 'D38EJ8LF'
      pin: 0
 
-The example would search for a USB gpiochip with the key `ID_SERIAL_SHORT`
-and the value `D38EJ8LF` and use the pin 0 of this device.
-The `ID_SERIAL_SHORT` property is set by the usb_id builtin helper program.
+The example would search for a USB gpiochip with the key ``ID_SERIAL_SHORT``
+and the value ``D38EJ8LF`` and use the pin 0 of this device.
+The ``ID_SERIAL_SHORT`` property is set by the usb_id builtin helper program.
 
 Arguments:
   - match (dict): key and value pairs for a udev match, see `udev Matching`_
@@ -695,7 +695,7 @@ Writing images to disk requires installation of ``dd`` or optionally
 
 For mounting the file system and writing into it,
 `PyGObject <https://pygobject.readthedocs.io/>`_ must be installed.
-For Debian, the necessary packages are `python3-gi` and `gir1.2-udisks-2.0`.
+For Debian, the necessary packages are ``python3-gi`` and ``gir1.2-udisks-2.0``.
 This is not required for writing images to disks.
 
 Arguments:
@@ -1550,15 +1550,15 @@ This manager is automatically created when a resource derived from
 :any:`USBResource` (such as :any:`USBSerialPort`, :any:`IMXUSBLoader` or
 :any:`AndroidUSBFastboot`) is instantiated.
 
-To identify the kernel device which corresponds to a configured `USBResource`,
+To identify the kernel device which corresponds to a configured :any:`USBResource`,
 each existing (and subsequently added) kernel device is matched against the
 configured resources.
-This is based on a list of `match entries` which must all be tested
+This is based on a list of *match entries* which must all be tested
 successfully against the potential kernel device.
 Match entries starting with an ``@`` are checked against the device's parents
 instead of itself; here one matching parent causes the check to be successful.
 
-A given `USBResource` class has builtin match entries that are checked first,
+A given :any:`USBResource` class has builtin match entries that are checked first,
 for example that the ``SUBSYSTEM`` is ``tty`` as in the case of the
 :any:`USBSerialPort`.
 Only if these succeed, match entries provided by the user for the resource
@@ -2977,7 +2977,7 @@ tool.
 Binds to:
   mux:
     - `LXAUSBMux`_
-    - `NetworkLXAUSBMux`
+    - `NetworkLXAUSBMux`_
 
 Implements:
   - None yet
@@ -2998,7 +2998,7 @@ tool.
 Binds to:
   mux:
     - `USBSDWireDevice`_
-    - `NetworkUSBSDWireDevice`
+    - `NetworkUSBSDWireDevice`_
 
 Implements:
   - None yet
@@ -3030,7 +3030,7 @@ Arguments:
 Although the driver can be used from Python code by calling the ``stream()``
 method, it is currently mainly useful for the ``video`` subcommand of
 ``labgrid-client``.
-It supports the `Logitech HD Pro Webcam C920` with the USB ID 046d:082d and a
+It supports the *Logitech HD Pro Webcam C920* with the USB ID ``046d:082d`` and a
 few others.
 More cameras can be added to ``get_qualities()`` and ``get_pipeline()`` in
 ``labgrid/driver/usbvideodriver.py``.
@@ -3078,7 +3078,7 @@ Arguments:
 Currently, it can be used by the ``labgrid-client`` ``tmc`` subcommands to show
 (and save) a screenshot, to show per channel measurements and to execute raw
 TMC commands.
-It only supports the `Keysight DSO-X 2000` series (with the USB ID 0957:1798),
+It only supports the *Keysight DSO-X 2000* series (with the USB ID ``0957:1798``),
 but more devices can be added by extending ``on_activate()`` in
 ``labgrid/driver/usbtmcdriver.py`` and writing a corresponding backend in
 ``labgrid/driver/usbtmc/``.
@@ -3225,14 +3225,14 @@ flashed.
 XenaDriver
 ~~~~~~~~~~
 The :any:`XenaDriver` allows to use Xena networking test equipment.
-Using the `xenavalkyrie` library a full API to control the tester is available.
+Using the ``xenavalkyrie`` library a full API to control the tester is available.
 
 Binds to:
   xena_manager:
     - `XenaManager`_
 
 The driver is supposed to work with all Xena products from the "Valkyrie Layer 2-3 Test platform"
-Currently tested on a `XenaCompact` chassis equipped with a `1 GE test module`.
+Currently tested on a *XenaCompact* chassis equipped with a *1 GE test module*.
 
 DockerDriver
 ~~~~~~~~~~~~
@@ -3269,7 +3269,7 @@ Arguments:
         containers storage. Throw an error if no image is found and the pull
         fails.
       - never: Never pull the image but use the one from the local containers
-        storage. Throw a `docker.errors.ImageNotFound` if no image is found.
+        storage. Throw a ``docker.errors.ImageNotFound`` if no image is found.
 
   - command (str): optional, command to run in the container (depends on image)
   - volumes (list): optional, list to configure volumes mounted inside the container
@@ -3422,6 +3422,8 @@ Strategies
 Strategies are used to ensure that the device is in a certain state during a test.
 Such a state could be the bootloader or a booted Linux kernel with shell.
 
+.. _conf-bareboxstrategy:
+
 BareboxStrategy
 ~~~~~~~~~~~~~~~
 A :any:`BareboxStrategy` has four states:
@@ -3622,7 +3624,7 @@ StepReporter
 .. warning::
     The StepReporter is deprecated, use the `StepLogger`_ instead.
 
-The :any:`StepReporter` outputs individual labgrid steps to `STDOUT`.
+The :any:`StepReporter` outputs individual labgrid steps to ``STDOUT``.
 
 .. doctest::
 
@@ -3836,8 +3838,8 @@ Exporter Configuration
 The exporter is configured by using a YAML file (with a syntax similar to the
 environment configs used for pytest) or by instantiating the :any:`Environment`
 object.
-To configure the exporter, you need to define one or more `resource groups`,
-each containing one or more `resources`.
+To configure the exporter, you need to define one or more *resource groups*,
+each containing one or more *resources*.
 The syntax for exported resource names is ``<exporter>/<group>/<class>/<name>``,
 which allows the exporter to group resources for various usage scenarios, e.g.
 all resources of a specific place or for a specific test setup.
@@ -3861,7 +3863,7 @@ The basic structure of an exporter configuration file is:
        <params>
 
 By default, the class name is inferred from the resource name,
-and `<params>` will be passed to its constructor.
+and ``<params>`` will be passed to its constructor.
 For USB resources, you will most likely want to use :ref:`udev-matching` here.
 
 As a simple example, here is one group called ``usb-hub-in-rack12`` containing

doc/development.rst

@@ -278,7 +278,7 @@ added.
   ``broken`` attribute and raise a ``StrategyError`` for the original and all
   subsequent calls to the decorated methods.
 
-Lets take a look at the builtin `BareboxStrategy`.
+Lets take a look at the builtin :ref:`BareboxStrategy <conf-bareboxstrategy>`.
 The Status enum for the BareboxStrategy:
 
 ::
@@ -289,7 +289,7 @@ The Status enum for the BareboxStrategy:
        barebox = 2
        shell = 3
 
-defines three custom states and the `unknown` state as the start point.
+defines three custom states and the ``unknown`` state as the start point.
 These three states are handled in the transition function:
 
 ::
@@ -312,13 +312,13 @@ These three states are handled in the transition function:
         self.barebox.await_boot()
         self.target.activate(self.shell)
 
-Here, the `barebox` state simply cycles the board and activates the driver,
-while the `shell` state uses the barebox state to cycle the board and then boot
+Here, the ``barebox`` state simply cycles the board and activates the driver,
+while the ``shell`` state uses the barebox state to cycle the board and then boot
 the linux kernel.
-The `off` state switches the power off.
+The ``off`` state switches the power off.
 
 Oftentimes it is also necessary to wait for specific resources to appear before
-a transition can be continued. The `await_resources` function of the target
+a transition can be continued. The ``await_resources()`` function of the target
 implements this functionality, it expects a list of resources to wait for and
 optionally takes a timeout and whether the resource should be available or
 unavailable.
@@ -514,32 +514,33 @@ A transition describes a path, or a part of a path, through a GraphStrategy
 graph.
 Every State in the graph has a auto generated default path starting from the
 root state.
-So using the given example, the GraphStrategy would call the states `unknown`,
-`boot_via_nand`, `barebox`, and `linux_shell` in this order if
+So using the given example, the GraphStrategy would call the states ``unknown``,
+``boot_via_nand``, ``barebox``, and ``linux_shell`` in this order if
 ``transition('linux_shell')`` would be called.
-The GraphStrategy would prefer `boot_via_nand` over `boot_via_nfs` because
-`boot_via_nand` is mentioned before `boot_via_nfs` in the dependencies of
-`barebox`. If you want to reach via `boot_via_nfs` the call would look like
+The GraphStrategy would prefer ``boot_via_nand`` over ``boot_via_nfs`` because
+``boot_via_nand`` is mentioned before ``boot_via_nfs`` in the dependencies of
+``barebox``. If you want to reach via ``boot_via_nfs`` the call would look like
 this: ``transition('linux_shell', via='boot_via_nfs')``.
 
 A transition can be incremental. If we trigger a transition with
-``transition('barebox')`` first, the states `unknown`, `boot_via_nand` and
-`barebox` will be called in this order. If we trigger a transition
-``transition('linux_shell')`` afterwards only `linux_shell` gets called. This
-happens because `linux_shell` is reachable from `barebox` and the Strategy
+``transition('barebox')`` first, the states ``unknown``, ``boot_via_nand`` and
+``barebox`` will be called in this order. If we trigger a transition
+``transition('linux_shell')`` afterwards only ``linux_shell`` gets called. This
+happens because ``linux_shell`` is reachable from ``barebox`` and the Strategy
 holds state of the last walked path.
 But there is a catch! The second, incremental path must be *fully* incremental
 to the previous path!
-For example: Lets say we reached `barebox` via `boot_via_nfs`,
+For example: Lets say we reached ``barebox`` via ``boot_via_nfs``,
 (``transition('barebox', via='boot_via_nfs')``). If we trigger
 ``transition('linux_shell')`` afterwards the GraphStrategy would compare the last
-path `'unknown', 'boot_via_nfs', 'barebox'` with the default path to
-`linux_shell` which would be
-`'unknown', 'boot_via_nand', 'barebox', 'linux_shell'`, and decides the path
+path ``'unknown', 'boot_via_nfs', 'barebox'`` with the default path to
+``linux_shell`` which would be
+``'unknown', 'boot_via_nand', 'barebox', 'linux_shell'``, and decides the path
 is not fully incremental and starts over by the root state. If we had given
-the second transition `boot_via_nfs` like in the first transition the paths
+the second transition ``boot_via_nfs`` like in the first transition the paths
 had been incremental.
 
+.. _sshmanager:
 
 SSHManager
 ----------
@@ -577,7 +578,7 @@ or get and put files:
 
 ManagedFile
 -----------
-While the `SSHManager` exposes a lower level interface to use SSH Connections,
+While the :ref:`SSHManager <sshmanager>` exposes a lower level interface to use SSH Connections,
 the ManagedFile provides a higher level interface for file upload to another
 host. It is meant to be used in conjunction with a remote resource, and store
 the file on the remote host with the following pattern:
@@ -586,9 +587,9 @@ the file on the remote host with the following pattern:
 
    /tmp/labgrid-<username>/<sha256sum>/<filename>
 
-Additionally it provides `get_remote_path()` to retrieve the complete file path,
+Additionally it provides ``get_remote_path()`` to retrieve the complete file path,
 to easily employ it for driver implementations.
-To use it in conjunction with a `Resource` and a file:
+To use it in conjunction with a *Resource* and a file:
 
 .. testsetup:: managed-file
 
@@ -607,7 +608,7 @@ To use it in conjunction with a `Resource` and a file:
    >>> mf.sync_to_resource()
    >>> path = mf.get_remote_path()
 
-Unless constructed with `ManagedFile(..., detect_nfs=False)`, ManagedFile
+Unless constructed with ``ManagedFile(..., detect_nfs=False)``, ManagedFile
 employs the following heuristic to check if a file is stored on a NFS share
 available both locally and remotely via the same path:
 
@@ -624,7 +625,7 @@ ProxyManager
 The proxymanager is used to open connections across proxies via an attribute in
 the resource. This allows gated testing networks by always using the exporter as
 an SSH gateway to proxy the connections using SSH Forwarding. Currently this is
-used in the `SerialDriver` for proxy connections.
+used in the :any:`SerialDriver` for proxy connections.
 
 Usage:
 
@@ -662,8 +663,8 @@ Workflow
 - Changes should be submitted via a `GitHub pull request
   <https://github.com/labgrid-project/labgrid/pulls>`_.
 - Try to limit each commit to a single conceptual change.
-- Add a signed-of-by line to your commits according to the `Developer's
-  Certificate of Origin` (see below).
+- Add a signed-of-by line to your commits according to the *Developer's
+  Certificate of Origin* (see below).
 - Check that the tests still work before submitting the pull request. Also
   check the CI's feedback on the pull request after submission.
 - When adding new drivers or resources, please also add the corresponding

doc/getting_started.rst

@@ -3,7 +3,7 @@ Getting Started
 
 This section of the manual contains introductory tutorials for installing
 labgrid, running your first test and setting up the distributed infrastructure.
-For an overview about the basic design and components of `labgrid`, read the
+For an overview about the basic design and components of *labgrid*, read the
 :ref:`overview` first.
 
 Installation
@@ -80,24 +80,24 @@ installation. An example for snmp support is:
 
 Onewire
 +++++++
-Onewire support requires the `libow` library with headers, installable on debian
-via the `libow-dev` package. Use the `onewire` extra to install the correct
+Onewire support requires the ``libow`` library with headers, installable on debian
+via the ``libow-dev`` package. Use the ``onewire`` extra to install the correct
 onewire library version in addition to the normal installation.
 
 SNMP
 ++++
-SNMP support requires to additional packages, `pysnmp` and `pysnmpmibs`. They
-are included in the `snmp` extra.
+SNMP support requires to additional packages, ``pysnmp`` and ``pysnmpmibs``. They
+are included in the ``snmp`` extra.
 
 Modbus
 ++++++
-Modbus support requires an additional package `pyModbusTCP`. It is included in
-the `modbus` extra.
+Modbus support requires an additional package ``pyModbusTCP``. It is included in
+the ``modbus`` extra.
 
 ModbusRTU
 +++++++++
-Modbus support requires an additional package `minimalmodbus`. It is included in
-the `modbusrtu` extra.
+Modbus support requires an additional package ``minimalmodbus``. It is included in
+the ``modbusrtu`` extra.
 
 Running Your First Test
 -----------------------
@@ -198,8 +198,8 @@ Each group contains one or more resource declarations and optionally a location
 string.
 
 For example, to export a ``USBSerialPort`` with ``ID_SERIAL_SHORT`` of
-``ID23421JLK``, the group name `example-group` and the location
-`example-location`:
+``ID23421JLK``, the group name ``example-group`` and the location
+``example-location``:
 
 .. code-block:: yaml
 
@@ -251,7 +251,7 @@ More information about the exporter configuration file can be found
 Restart the exporter to activate the new configuration.
 
 .. Attention::
-   The `ManagedFile` will create temporary uploads in the exporters
+   The :any:`ManagedFile` will create temporary uploads in the exporters
    ``/var/cache/labgrid`` directory. This directory needs to be created manually
    and should allow write access for users. The ``/contrib`` directory in the
    labgrid-project contains a tmpfiles configuration example to automatically
@@ -276,7 +276,7 @@ Finally we can test the client functionality, run:
     kiwi/example-group-2/NetworkSerialPort
 
 You can see the available resources listed by the coordinator. The groups
-`example-group` and `example-group-2` should be available there.
+``example-group`` and ``example-group-2`` should be available there.
 
 To show more details on the exported resources, use ``-v`` (or ``-vv``):
 
@@ -420,7 +420,7 @@ Follow these instructions to install the systemd files on your machine(s):
       # systemctl start labgrid-exporter
 
 #. Optionally, for users being able to upload files to the exporter, add them
-   to the `labgrid` group on the exporter machine:
+   to the ``labgrid`` group on the exporter machine:
 
    .. code-block:: console
 
@@ -450,4 +450,4 @@ retrieve it in your test and call the ``transition(status)`` function.
 See the section about the various :ref:`shipped strategies <conf-strategies>`
 for examples on this.
 
-An example using the pytest plugin is provided under `examples/strategy`.
+An example using the pytest plugin is provided under ``examples/strategy``.