doc: fix and clarify several paragraphs

Clarify overly complicated sentences. Also fix grammatically wrong
sentences.

Use "bootloader" spelling across project, which seems to be the wider
used alternative (as opposed to "boot loader").

Signed-off-by: Bastian Krause <[email protected]>

doc/configuration.rst

@@ -358,7 +358,7 @@ Used by:
 
 USBEthernetInterface
 ~~~~~~~~~~~~~~~~~~~~
-A USBEthernetInterface resource describes a USB device Ethernet adapter.
+A USBEthernetInterface resource describes a USB ethernet adapter.
 
 .. code-block:: yaml
 
@@ -558,8 +558,8 @@ A NetworkFlashrom descibes an `Flashrom`_ available on a remote computer.
 
 XenaManager
 ~~~~~~~~~~~
-A XenaManager resource describe a Xena Manager instance which is the instance the
-Xena Driver must connect to in order to configure a Xena chassis.
+A XenaManager resource describes a Xena Manager instance which is the instance the
+`XenaDriver`_ must connect to in order to configure a Xena chassis.
 
 .. code-block:: yaml
 
@@ -887,32 +887,31 @@ SmallUBootDriver
 A SmallUBootDriver interfaces with stripped-down UBoot variants that are
 sometimes used in cheap consumer electronics.
 
-SmallUBootDriver is meant as a driver for UBoot with only little
-functionality compared to standard a standard UBoot.
+SmallUBootDriver is meant as a driver for UBoot with only little functionality
+compared to a standard UBoot.
 Especially is copes with the following limitations:
 
 - The UBoot does not have a real password-prompt but can be activated by
   entering a "secret" after a message was displayed.
-- The command line is does not have a build-in echo command. Thus this
-  driver uses 'Unknown Command' messages as marker before and after the
-  output of a command.
-- Since there is no echo we can not return the exit code of the command.
+- The command line does not have a built-in echo command.
+  Thus this driver uses 'Unknown Command' messages as marker before and after
+  the output of a command.
+- Since there is no echo we cannot return the exit code of the command.
   Commands will always return 0 unless the command was not found.
 
 This driver needs the following features activated in UBoot to work:
 
-- The UBoot must not have real password prompt. Instead it must be
-  keyword activated.
+- The UBoot must not have a real password prompt. Instead it must be keyword
+  activated.
   For example it should be activated by a dialog like the following:
 
   - UBoot: "Autobooting in 1s..."
   - Labgrid: "secret"
   - UBoot: <switching to console>
 
-- The UBoot must be able to parse multiple commands in a single
-  line separated by ";".
-- The UBoot must support the "bootm" command to boot from a
-  memory location.
+- The UBoot must be able to parse multiple commands in a single line separated
+  by ";".
+- The UBoot must support the "bootm" command to boot from a memory location.
 
 Binds to:
   - :any:`ConsoleProtocol` (see `SerialDriver`_)
@@ -1208,8 +1207,8 @@ SerialPortDigitalOutputDriver
 The SerialPortDigitalOutputDriver makes it possible to use a UART
 as a 1-Bit general-purpose digital output.
 
-This driver sits on top of a SerialDriver and uses the it's pyserial-
-port to control the flow control lines.
+This driver acts on top of a SerialDriver and uses the its pyserial port to
+control the flow control lines.
 
 Implements:
   - :any:`DigitalOutputProtocol`
@@ -1481,7 +1480,7 @@ The qemudriver also requires the specification of:
 
 SigrokDriver
 ~~~~~~~~~~~~
-The SigrokDriver uses a SigrokDevice Resource to record samples and provides
+The SigrokDriver uses a SigrokDevice resource to record samples and provides
 them during test runs.
 
 Binds to:
@@ -1498,7 +1497,7 @@ The driver can be used in test cases by calling the `capture`, `stop` and
 
 SigrokPowerDriver
 ~~~~~~~~~~~~~~~~~
-The SigrokPowerDriver uses a `SigrokUSBSerialDevice`_ Resource to control a
+The SigrokPowerDriver uses a `SigrokUSBSerialDevice`_ resource to control a
 programmable power supply.
 
 Binds to:
@@ -1601,8 +1600,8 @@ installed flashrom utility.
 
 XenaDriver
 ~~~~~~~~~~
-The XenaDriver allows to use Xena networking tests equipment. Using the xenavalkyrie library
-a full API to control the tester is available.
+The XenaDriver allows to use Xena networking test equipment.
+Using the `xenavalkyrie` library a full API to control the tester is available.
 
 Binds to:
   xena_manager:
@@ -1651,7 +1650,7 @@ Strategies
 ----------
 
 Strategies are used to ensure that the device is in a certain state during a test.
-Such a state could be the boot loader or a booted Linux kernel with shell.
+Such a state could be the bootloader or a booted Linux kernel with shell.
 
 BareboxStrategy
 ~~~~~~~~~~~~~~~
@@ -1672,7 +1671,7 @@ to transition to the shell state:
    s.transition("shell")
 
 
-this command would transition from the boot loader into a Linux shell and
+this command would transition from the bootloader into a Linux shell and
 activate the shelldriver.
 
 ShellStrategy
@@ -1715,7 +1714,7 @@ to transition to the shell state:
    s.transition("shell")
 
 
-this command would transition from the boot loader into a Linux shell and
+this command would transition from the bootloader into a Linux shell and
 activate the shelldriver.
 
 DockerShellStrategy
@@ -1897,7 +1896,7 @@ To bind the correct driver to the correct resource, explicit ``name`` and
         port: 'bar'
 
 The property name for the binding (e.g. `port` in the example above) is
-documented for each individual driver under this chapter.
+documented for each individual driver in this chapter.
 
 The YAML configuration file also supports templating for some substitutions,
 these are:

doc/development.rst

@@ -159,7 +159,7 @@ Writing a Resource
 -------------------
 
 To add a new resource to labgrid, we import attr into our new resource file.
-Additionally we need the :any:`target_factory` and the common Resource class.
+Additionally we need the :any:`target_factory` and the common ``Resource`` class.
 
 ::
 
@@ -245,7 +245,7 @@ Start by creating a strategy skeleton:
 
 
 The ``bindings`` variable needs to declare the drivers necessary for the
-strategy, usually one for power, boot loader and shell.
+strategy, usually one for power, bootloader and shell.
 It is possible to reference drivers via their protocol, e.g.
 ``ConsoleProtocol``.
 Note that drivers which implement multiple protocols must not be referenced
@@ -254,7 +254,8 @@ The ``Status`` class needs to be extended to cover the states of your strategy,
 then for each state an ``elif`` entry in the transition function needs to be
 added.
 
-Lets take a look at the builtin `BareboxStrategy`. The Status enum for Barebox:
+Lets take a look at the builtin `BareboxStrategy`.
+The Status enum for the BareboxStrategy:
 
 ::
 
@@ -460,15 +461,17 @@ To use it in conjunction with a `Resource` and a file:
    path = mf.get_remote_path()
 
 Unless constructed with `ManagedFile(..., detect_nfs=False)`, ManagedFile
-employs the following heuristic to check if a file is on NFS and if so, foregoes
-the transfer and `get_remote_path()` just returns the local path (which is
-identical to the remote path in this case):
+employs the following heuristic to check if a file is stored on a NFS share
+available both locally and remotely via the same path:
 
   - check if GNU coreutils stat(1) with option --format exists on local and
     remote system
   - check if inode number, total size and birth/modification timestamps match
     on local and remote system
 
+If this is the case the actual file transfer in ``sync_to_resource`` is
+skipped.
+
 ProxyManager
 ------------
 The proxymanager is used to open connections across proxies via an attribute in
@@ -597,7 +600,7 @@ Step Tracing
 ~~~~~~~~~~~~
 
 The Step infrastructure already collects timing and nesting information on
-executed commands, but is currently only used for in pytest or via the
+executed commands, but is currently only used in the pytest plugin or via the
 standalone StepReporter.
 By writing these events to a file (or sqlite database) as a trace, we can
 collect data over multiple runs for later analysis.

doc/overview.rst

@@ -275,7 +275,7 @@ exporter1/hub1-port1/\*
   (such as a USB ROM-Loader interface, Android fastboot and a USB serial gadget
   in Linux).
 
-To avoid conflicting access to the same resources, a place must be `aquired`
+To avoid conflicting access to the same resources, a place must be `acquired`
 before it is used and the coordinator also keeps track of which user on which
 client host has currently acquired the place.
 The resource matches are only evaluated while a place is being acquired and cannot be
@@ -353,7 +353,7 @@ connections to remote resources made available by this exporter need to be
 tunneled using a SSH connection.
 On the other hand, clients may need to access the remote infrastrucure using a
 SSH tunnel. In this case the :code:`LG_PROXY` environment variable needs to be
-set to the remote host which should tunnel the connections. The client than
+set to the remote host which should tunnel the connections. The client then
 forwards all network traffic through SSH, even the coordinator connection is
 forwarded. This means that with :code:`LG_PROXY` and :code:`LG_CROSSBAR` labgrid can be used
 fully remotely with only a SSH connection as a requirement.

doc/usage.rst

@@ -7,7 +7,7 @@ Remote Access
 -------------
 
 As described in :ref:`remote-resources-and-places`, one of labgrid's main
-features is making access to boards connected to other hosts transparent for
+features is granting access to boards connected to other hosts transparent for
 the client.
 To get started with remote access, take a look at
 :ref:`remote-getting-started`.
@@ -517,16 +517,16 @@ For this example, you should get a report similar to this:
 Feature Flags
 ~~~~~~~~~~~~~
 Labgrid includes support for feature flags on a global and target scope.
-They will be concatenated and compared to a pytest mark on the test to decide
-whether the test can run with the available features.::
+Adding a ``@pytest.mark.lg_feature`` decorator to a test ensures it is only
+executed if the desired feature is available::
 
    import pytest
 
    @pytest.mark.lg_feature("camera")
    def test_camera(target):
       [...]
 
-together with an example environment configuration:
+Here's an example environment configuration:
 
 .. code-block:: yaml
 
@@ -537,7 +537,7 @@ together with an example environment configuration:
       resources: {}
       drivers: {}
 
-would run the above test, however the following configuration would skip the
+This would run the above test, however the following configuration would skip the
 test because of the missing feature:
 
 .. code-block:: yaml
@@ -549,10 +549,9 @@ test because of the missing feature:
       resources: {}
       drivers: {}
 
-This is also reported in the pytest execution as a skipped test with the reason
-being the missing feature.
+pytest will record the missing feature as the skip reason.
 
-For tests with multiple required features, pass them as a list to pytest:::
+For tests with multiple required features, pass them as a list to pytest::
 
    import pytest
 
@@ -574,7 +573,7 @@ features key:
       resources: {}
       drivers: {}
 
-This yaml would combine both the global and the target features.
+This YAML configuration would combine both the global and the target features.
 
 
 Test Reports

examples/usbpower/README.rst

@@ -16,8 +16,8 @@ examplestrategy.py
   Custom strategy which controls the USB-SD-Mux and the USB port power.
 
 test_example.py
-  Testsuite (based on pytest) to run a simple command in Barebox, Shell and
-  Barebox again.
+  Testsuite (based on pytest) to run a simple command in barebox, shell and
+  barebox again.
 
 exports.yaml
   Configuration file for labgrid-exporter to export these resources over the