docs: grammar and language improvements

docs/articles/bundled-utilities.rst

@@ -1,8 +1,8 @@
 Ready to Use Utilities
 ######################
 
-Pytest-mh codebase contains several generic, ready to use utilities that you can
-easily add to your hosts and roles. These utilities add support for various
+``pytest-mh`` codebase contains several generic, ready to use utilities that
+can be added to hosts and roles. These utilities add support for various
 project independent tasks, such as reading and writing files, managing firewall,
 automatic collection of core dumps and much more.
 

docs/articles/bundled-utilities/auditd.rst

@@ -59,7 +59,7 @@ category.
 .. warning::
 
     It is not possible to run auditd inside a container therefore this utility
-    can detect AVC denials if the remote host is a virtual machine or bare
+    can detect AVC denials only if the remote host is a virtual machine or bare
     metal.
 
     If you run your tests on containerized environment as well as on virtual

docs/articles/bundled-utilities/firewall.rst

@@ -1,9 +1,9 @@
 Firewall: Managing Network Access
 #################################
 
-The :mod:`pytest_mh.utils.firewall` provides generic interface to remote system
-firewall as well as two specific implementations of this interface: Firewalld
-and Windows Firewall.
+The :mod:`pytest_mh.utils.firewall` provides a generic interface to manage the
+remote system firewall as well as two specific implementations of this
+interface: Firewalld and Windows Firewall.
 
 These utilities allows you to create inbound and outbound rules to block or
 allow access to specific ports, IP addresses or hostnames.
@@ -52,6 +52,6 @@ allow access to specific ports, IP addresses or hostnames.
 .. note::
 
     If you create a new firewall rule to block a connection, connections that
-    are already established may not be terminated. Therefore, if you start
+    are already established may not be terminated. If you start
     blocking a connection and the application under test is already running,
     make sure that the application also drops active connections.

docs/articles/bundled-utilities/fs.rst

@@ -1,8 +1,8 @@
-Filesystem: Manipulating Files and Folders
-##########################################
+Filesystem: Manipulating Files and Directories
+##############################################
 
-The :mod:`pytest_mh.utils.fs` module provides access to remote files and folders:
-reading and writing files, creating folders, making temporary folders and files
+The :mod:`pytest_mh.utils.fs` module provides access to remote files and directories:
+reading and writing files, creating directories, making temporary directories and files
 and more.
 
 A backup is created for every path that is changed during a test and it is
@@ -18,7 +18,7 @@ and context) are fully restored.
 .. note::
 
     Currently, we only provide :class:`~pytest_mh.utils.fs.LinuxFileSystem` to
-    manipulate files and folders on Linux systems. Contributions for Windows
+    manipulate files and directions on Linux systems. Contributions for Windows
     world are welcomed.
 
 .. code-block:: python

docs/articles/bundled-utilities/journald.rst

@@ -1,7 +1,7 @@
 Journald: Searching in the Journal
 ##################################
 
-Systemd-journald is the daemon that collects system logs nowadays. This utility
+``systemd-journald`` is the daemon that collects system logs. This utility
 dumps journal contents to a file and stores it as a test artifact. It also
 exposes an API to run queries against the journal to search for messages that
 were produced during the test run.

docs/articles/extending.rst

@@ -1,7 +1,7 @@
 Extending pytest-mh for Your Needs
 ##################################
 
-Pytest-mh uses a yaml-formatted configuration file that contains the list of
+``pytest-mh`` uses a yaml-formatted configuration file that contains the list of
 multihost domains, hosts and their roles that are required for the tests. These
 configuration entities are converted into their Python representations that can
 and should be extended to provide additional configuration and high level API

docs/articles/extending/multihost-domains.rst

@@ -53,7 +53,7 @@ overriding the parent class methods. The configuration dictionary can be
 accessed by :attr:`~pytest_mh.MultihostDomain.confdict`, however it is
 recommended to place custom options under the ``config`` field which can be
 accessed directly through the :attr:`~pytest_mh.MultihostDomain.config`
-attribute. This way, it is possible to avoid name collisions if pytest-mh
+attribute. This way, it is possible to avoid name collisions if ``pytest-mh``
 introduces new options in the future.
 
 It is also possible to override or extend all public methods to further affect

docs/articles/extending/multihost-hosts.rst

@@ -16,7 +16,7 @@ should be available to all tests.
     The host class can be also used to provide high-level API for your project,
     however remember that the test has direct access to the
     :class:`MultihostRole` objects and only indirect access to the host objects
-    (via the role). Therefore vast majority of your high-level API should be
+    (via the role). Therefore the vast majority of your high-level API should be
     placed in the role object in order to provide most direct access.
 
 .. code-block:: python

docs/articles/extending/multihost-topologies.rst

@@ -1,8 +1,8 @@
 Multihost Topologies
 ####################
 
-Multihost topology is the core of pytest-mh. It defines the requirements of a
-test -- what multihost domains and roles (and how many) are required to run the
+Multihost topology is the core of ``pytest-mh``. It defines the requirements of
+a test -- what multihost domains and roles (and how many) are required to run the
 test. If the current environment defined in the configuration file does not meet
 the requirements of the topology then the test is silently skipped (in pytest
 terminology the test is not collected) and you will not even see it in the
@@ -67,15 +67,15 @@ file:
 
 .. note::
 
-    See that all three servers from the third example are placed inside a single
+    All three servers from the third example are placed inside a single
     multihost domain. This is because all these servers contains the same data
     and it should not matter to which one the client talks to. If they serve
     different data, they should be placed in different multihost domains.
 
 Topology Marker
 ===============
 
-Pytest-mh implements a new marker ``@pytest.mark.topology`` which is converted
+``pytest-mh`` implements a new marker ``@pytest.mark.topology`` which is converted
 into an instance of :class:`~pytest_mh.TopologyMark`. This marker is used to
 assign a topology to a test. One test can be associated with multiple topologies
 -- this is called :ref:`topology parametrization <topology_parametrization>`. In
@@ -323,8 +323,8 @@ Then make this a topology marker type by setting
 Topology Controller
 ===================
 
-Pytest-mh allows you to run tests against multiple topologies in one pytest run.
-It is not always possible or desired to provide distinct set of host for each
+``pytest-mh`` allows running tests against multiple topologies in one pytest run.
+It is not always possible or desired to provide a distinct set of hosts for each
 topology, instead the hosts are usually being reused. However, each topology
 typically requires different environment setup.
 :class:`~pytest_mh.TopologyController` gives you access to topology setup and
@@ -409,7 +409,7 @@ With the topology controller, you can:
 Topology Parametrization
 ========================
 
-A test parametrization is a way to share a test code for different input
+Test parametrization is a way to share test code for different input
 arguments and therefore test different configurations or user inputs easily and
 thus quickly extend the code coverage. Pytest allows this by using the
 ``@pytest.mark.parametrize`` `mark <pytest-parametrize_>`_.
@@ -433,7 +433,7 @@ topology). For example:
   one test for hostname resolution but let the client library use all transfer
   protocols, one by one.
 
-In each case, it is desirable to have a single test which, however, is run with
+In each case, it is desirable to have a single test which is run with
 different backends or server configurations. To provide a real world example,
 we can check out one of the basic SSSD tests. This test has multiple topologies
 assigned and it is run once per each topology: LDAP, IPA, Samba and AD.

docs/articles/extending/multihost-utilities.rst

@@ -3,7 +3,7 @@ Multihost Utilities
 
 :class:`~pytest_mh.MultihostUtility` can be used to share code between different
 :class:`~pytest_mh.MultihostRole` classes, in addition
-:class:`~pytest_mh.MultihostReentrantUtility` can be used to share code beetween
+:class:`~pytest_mh.MultihostReentrantUtility` can be used to share code between
 roles but also between :class:`~pytest_mh.MultihostHost` classes.
 
 .. seealso::
@@ -18,7 +18,7 @@ MultihostUtility
 All instances of :class:`~pytest_mh.MultihostUtility` that are available within
 :class:`~pytest_mh.MultihostRole` classes are automatically setup and teardown
 before and after the test. This can be used to provide high-level API that also
-cleans up after itself and share this code between multiple roles.
+cleans up after itself and to share this code between multiple roles.
 
 .. code-block:: python
     :caption: Example utility to manage local users
@@ -150,7 +150,7 @@ MultihostReentrantUtility
 multiple setup scopes and therefore can be safely used inside
 :class:`~pytest_mh.MultihostHost`. You can understand a setup scope as a pair of
 setup and teardown hooks, every code that is executed between these calls is a
-setup scope. Pytest-mh currently defines the following scopes:
+setup scope. ``pytest-mh`` currently defines the following scopes:
 
 .. code-block:: text
     :caption: Setup scopes

docs/articles/get-started.rst

@@ -4,9 +4,8 @@ Getting Started
 Pytest-mh is not a plugin to support unit testing. It is a plugin designed to
 support testing your application as a complete product, this is often referred
 to as a black-box, application or system testing. The application is installed
-on the target host and tested there by running commands on the host (and on
-other hosts that are required). These hosts can be virtual machines or
-containers.
+on the target host and tested by running commands on the host (and on other
+hosts that are required). These hosts can be virtual machines or containers.
 
 .. seealso::
 
@@ -17,7 +16,7 @@ As such, it is often useful to write a high level API that will support testing
 your application and make your test smaller and more readable. This may require
 a non-trivial initial investment, but it will pay off in the long run. However,
 implementing such API is not required and it is perfectly possible to run
-commands on the host directly from each test. That, however, makes tests usually
+commands on the host directly from each test. This approach makes tests usually
 larger and more difficult to understand and maintain -- but every project is
 different and it is up to you to choose how are you going to test your
 application.
@@ -74,7 +73,7 @@ Our goals are:
 As you can see, these goals require us to write 12 tests in total. But since the
 result is the same and only the data is fetched from different sources, we can
 use :ref:`topology parametrization <topology_parametrization>`. Topology
-parametrization will allow us to write only one test but run it against
+parametrization allows us to write only one test but run it against
 different backends and thus we will do less work but get more code coverage.
 
 We will take the following steps to achieve it:
@@ -128,14 +127,14 @@ individual classes.
 Define multihost topologies
 ---------------------------
 
-This is the first step when designing a test framework since it tells you what
+This is the first step when designing a test framework since it defines what
 hosts and roles your project needs. For sudo, we want sudo rules to be fetched
 from different sources. We can consider each data source to be a single
 topology.
 
 * **sudoers**
 
-  * we only need one host
+  * only one host needed
   * users, groups and sudo rules will be created locally
 
 * **ldap**
@@ -171,7 +170,7 @@ topology group as a shortcut for :ref:`topology parametrization
 Write configuration file
 ------------------------
 
-The topology defines which hosts and roles are needed to run sudo test. We can
+The topology defines which hosts and roles are needed to run sudo tests. We can
 convert it into a configuration file that can be used to run all sudo tests.
 
 The configuration file will define one domain with two hosts - one ``client``
@@ -220,9 +219,9 @@ Python classes.
 Design and implement the framework
 ----------------------------------
 
-This part is rather more complicated and can not be treated universally as every
+This step is more complicated and can not be treated universally as every
 project has different needs. It is possible to use multiple building blocks
-provided by pytest-mh in order to build a high-level API for your tests, see
+provided by ``pytest-mh`` in order to build a high-level API for your tests, see
 :doc:`extending` and :doc:`life-cycle` to get a good grasp of all the classes
 and how to use them.
 
@@ -309,8 +308,8 @@ Enable pytest-mh in conftest.py
 -------------------------------
 
 When the test framework is written and ready to use, we can tell pytest to
-start using it in our tests. First, we tell pytest to load pytest-mh plugin and
-then we tell pytest-mh which config class it should instantiate.
+start using it in our tests. First, configure pytest to load pytest-mh plugin and
+then inform pytest-mh which config class it should instantiate.
 
 .. dropdown:: See the code
     :color: primary

docs/articles/life-cycle.rst

@@ -1,11 +1,10 @@
 Life Cycle and Hooks
 ####################
 
-One of the most fundamental features of pytest-mh is to provide users a way to
-setup hosts before a test is run, collect test artifacts and revert all changes
-that were done during the test afterwards. Therefore it provides multiple hooks
-that will execute your code in order to achieve smooth and extensive setup and
-teardown and more.
+One fundamental feature of ``pytest-mh`` is to provide users a way to setup
+hosts before a test is run, collect test artifacts and revert all changes
+that were done during the test. It provides multiple hooks that will execute
+your code in order to achieve smooth and extensive setup and teardown and more.
 
 .. toctree::
     :maxdepth: 2

docs/articles/life-cycle/artifacts-collection.rst

@@ -2,16 +2,16 @@ Artifacts Collection
 ####################
 
 Collecting logs and other artifacts from a test is a very important task,
-especially if the test fails. Most of the test frameworks allows you to collect
-artifacts that are explicitly configured. Pytest-mh has this feature as well but
-it also takes this a step further and allows you to collect and even produce
-artifacts dynamically after a test is finished.
+especially if the test fails. Most test frameworks allows you to collect
+artifacts that are explicitly configured. ``pytest-mh`` has this feature
+as well but it also takes this a step further and allows you to collect
+and even produce artifacts dynamically after a test is finished.
 
 This is especially useful if you do not want to rely on each test to produce
 artifacts that require additional commands to be run (for example a database
 dump). With pytest-mh, it is possible to implement this on a different level and
-therefore each test can focus solely on testing functionality, pytest-mh will
-take care of producing and collecting the extra artifacts.
+therefore each test can focus solely on testing functionality, ``pytest-mh``
+will take care of producing and collecting the extra artifacts.
 
 .. seealso::
 
@@ -41,7 +41,7 @@ take care of producing and collecting the extra artifacts.
 User-defined artifacts
 ======================
 
-The pytest-mh configuration file has a field ``artifacts`` in the host section
+The ``pytest-mh`` configuration file has a field ``artifacts`` in the host section
 where it is possible to define a list of artifacts that should be automatically
 downloaded from a host when a test is finished and before teardown is executed.
 This list can also contain a wildcard.
@@ -82,7 +82,7 @@ attribute of the class.
 New artifacts can also be produced when a test is finished, or the list of
 artifacts can be set more dynamically based on your own conditions (e.g.
 installation failed). To achieve this, it is possible to override
-``get_artifacts_list()`` method of each class. This method is used by pytest-mh
+``get_artifacts_list()`` method of each class. This method is used by ``pytest-mh``
 to obtain the list of artifacts to collect and it must return a ``set()`` of
 artifacts.
 

docs/articles/life-cycle/setup-and-teardown.rst

@@ -1,7 +1,7 @@
 Setup and Teardown Hooks
 ########################
 
-Pytest-mh provides multiple setup and teardown hooks that you can use to setup
+``pytest-mh`` provides multiple setup and teardown hooks that can be used to setup
 the test environment and later revert all changes that were done during the
 setup and testing.
 

docs/articles/life-cycle/skipping-tests.rst

@@ -1,15 +1,14 @@
 Skipping Tests
 ##############
 
-It is always possible to use pytest filtering options to run only the desired
-test. But often, it may be useful to skip a test based on some external
-condition: for example if the product was built with a certain feature or not.
-If the feature is not supported, tests that are using this feature must be
-skipped.
+Pytest filtering options are used to run only the desired tests, but it may
+be useful to skip a test based on some external condition: for example if
+the product was built with a certain feature or not. If the feature is not
+supported, tests that are using this feature must be skipped.
 
 It is not possible to accomplish this with the built-in ``pytest.mark.skipif``
 marker since it is evaluated too soon and only takes expressions, it does not
-provide access to the fixtures. However, pytest-mh provides alternative
+provide access to the fixtures. However, ``pytest-mh`` provides alternative
 solutions.
 
 .. seealso::

docs/articles/running-commands.rst

@@ -1,8 +1,8 @@
 Running Commands on Remote Hosts
 ################################
 
-Running commands on remote hosts is one of the fundamental features of
-pytest-mh. In order to do that, it provides abstraction over remote processes
+Running commands on remote hosts is a fundamental feature of
+``pytest-mh``. In order to do that, it provides abstraction over remote processes
 and a generic interface in the :class:`~pytest_mh.conn.Connection` class. There
 are currently two implementations of this interface:
 

docs/articles/running-commands/blocking-calls.rst

@@ -1,7 +1,7 @@
 Blocking Calls
 ##############
 
-It is possible to run a command using a blocking code, meaning the code will
+It is possible to run a command using a blocking call, meaning the code will
 block until the command is finished and its result is returned. The result is
 instance of :class:`~pytest_mh.conn.ProcessResult` and gives you access to
 return code, standard output and standard error output.

docs/articles/running-tests.rst

@@ -1,8 +1,8 @@
 Running Tests
 #############
 
-Pytest-mh is a pytest plugin, therefore all tests are run with ``pytest``. There
-are some additional command line arguments that you can use, all pytest-mh
+``pytest-mh`` is a pytest plugin, therefore all tests are run with ``pytest``.
+There are some additional command line arguments that you can use, all ``pytest-mh``
 arguments are prefixed with ``--mh-``. You can use the following command
 to find all pytest-mh related parameters:
 
@@ -49,7 +49,7 @@ parentheses.
 Useful parameters
 =================
 
-This is a short list of selected pytest-mh parameters that can be useful when
+This is a short list of selected ``pytest-mh`` parameters that can be useful when
 running tests locally.
 
 * ``--mh-topology``: Run only tests for selected topology
@@ -65,7 +65,7 @@ running tests locally.
 Debugging tests
 ===============
 
-Pytest-mh stores logs for each test run. These logs can be found among the test
+``pytest-mh`` stores logs for each test run. These logs can be found among the test
 artifacts in artifacts directory (by default ``./artifacts``). You can find them
 in: