docs: language corrections

Signed-off-by: Iker Pedrosa <[email protected]>

docs/articles/bundled-utilities.rst

@@ -39,8 +39,8 @@ add them to your role or host.
             """
 
 These utilities are automatically initialized, setup and teardown. You can start
-using them right away. Every change on the host that these utilities do during
-a test run is guarantied to be automatically reverted.
+using them right away. Any changes made to the host by these utilities during a
+test run will be automatically reverted.
 
 .. note::
 

docs/articles/bundled-utilities/auditd.rst

@@ -40,7 +40,7 @@ Everything else is fully automatic.
 If the ``avc_mode`` is set to ``fail``, it will change the outcome of the test
 to ``failed`` even if the test itself was successful. However, the original
 outcome is still visible in the verbose output. You can also set it to ``warn``
-to mark the test as ``AVC DENIAL`` but keep the test outcome intact; or to
+to mark the test as ``AVC DENIAL``, but keep the test outcome intact; or to
 ``ignore`` to only collect the audit logs without affecting the test outcome or
 category.
 

docs/articles/bundled-utilities/firewall.rst

@@ -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
-    blocking a connection and application under test is already running,
+    are already established may not be terminated. Therefore, 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

@@ -6,9 +6,9 @@ reading and writing files, creating folders, making temporary folders and files
 and more.
 
 A backup is created for every path that is changed during a test and it is
-restored after the test is finished. Therefore you do not have to worry about
-touching any path, the original contents and state (including ownership, mode
-and context) is fully restored.
+restored after the test is finished. Therefore, you don't have to worry about
+touching any paths, the original content and state (including ownership, mode
+and context) are fully restored.
 
 .. seealso::
 

docs/articles/extending.rst

@@ -35,8 +35,10 @@ The file is parsed into:
 * :class:`~pytest_mh.MultihostConfig`: top level object, container for the whole
   configuration
 * :class:`~pytest_mh.MultihostDomain`: the domain object, container for all
-  hosts within a domain, one for each domain
-* :class:`~pytest_mh.MultihostHost`: individual hosts, one for each host
+  hosts within a domain, one for each domain. From the previous example this
+  would be ``example``
+* :class:`~pytest_mh.MultihostHost`: individual hosts, one for each host. From
+  the previous example the name would be ``client``
 
 Additionally, each host has a role assigned. This role creates a
 :class:`~pytest_mh.MultihostRole` object, this object has a short lifespan and

docs/articles/extending/multihost-config.rst

@@ -28,7 +28,7 @@ However, it can also be used to add a custom top-level configuration options or
 extend the functionality of ``pytest.mark.topology`` marker. The configuration
 file contents can be accessed as a dictionary through
 :attr:`~pytest_mh.MultihostConfig.confdict`, however it is recommended to place
-custom options under the ``config`` field which can by accessed directly through
+custom options under the ``config`` field which can be accessed directly through
 the :attr:`~pytest_mh.MultihostConfig.config` attribute. This way, it is
 possible to avoid name collisions if pytest-mh introduces new options in the
 future.

docs/articles/extending/multihost-domains.rst

@@ -2,8 +2,8 @@ Multihost Domains
 #################
 
 :class:`~pytest_mh.MultihostDomain` has access to the domain part of the
-configuration file. Its main purpose is to map role names into a Python
-classes that will be used to create the host and role objects.
+configuration file. Its main purpose is to map role names into Python classes
+that will be used to create the host and role objects.
 
 .. code-block:: python
     :caption: Basic example of MultihostDomain
@@ -47,14 +47,14 @@ classes that will be used to create the host and role objects.
     scope and avoid circular dependency since :class:`~pytest_mh.MultihostHost`
     is a generic class that takes the domain class as a specific type.
 
-Similar to the :class:`~pytest_mh.MultihostConfig` class, it also possible to
-add custom configuration options or further extend functionality by 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 by accessed directly through
-the :attr:`~pytest_mh.MultihostDomain.config` attribute. This way, it is
-possible to avoid name collisions if pytest-mh introduces new options in the
-future.
+Similar to the :class:`~pytest_mh.MultihostConfig` class, it is also possible
+to add custom configuration options or further extend functionality by
+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
+introduces new options in the future.
 
 It is also possible to override or extend all public methods to further affect
 the behavior.

docs/articles/extending/multihost-hosts.rst

@@ -2,9 +2,9 @@ Multihost Hosts
 ###############
 
 :class:`~pytest_mh.MultihostHost` has access to the host part of the
-configuration file. Its main purpose is to setup and teardown the host and
-prepare it to run the tests and provide access to the main connection to the
-host over which is it possible to run commands on the host (see
+configuration file. Its main purpose is to setup and teardown the host,
+preparing it to run tests. It also provides the main connection to the host
+making it possible to run remote commands (see
 :attr:`~pytest_mh.MultihostHost.conn` attribute).
 
 The host objects are created once when pytest starts and live for the whole

docs/articles/extending/multihost-roles.rst

@@ -9,7 +9,7 @@ to implement high-level API for testing your project.
 
 .. seealso::
 
-    See :doc:`multihost-utilities` to see how is it possible to share code
+    See :doc:`multihost-utilities` to see how it is possible to share code
     between multiple role classes (and host classes).
 
 As a first example, we implement a basic code for a client role. This role

docs/articles/extending/multihost-topologies.rst

@@ -79,7 +79,7 @@ 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
-this case, the test is multiplied and run ones for all assigned topologies,
+this case, the test is multiplied and run once for all assigned topologies,
 therefore it is possible to re-use the test code for different setups/backends.
 
 The ``@pytest.mark.topology`` can take different types of arguments in order to
@@ -122,7 +122,7 @@ The built-in :class:`~pytest_mh.TopologyMark` supports ``controller`` (defaults
 to an instance of :class:`~pytest_mh.TopologyController`) and ``fixtures`` which
 defines mapping between hosts and pytest fixtures available to the test.
 
-The ``fixtures`` argument is a dictionary where key is the fixture name and
+The ``fixtures`` argument is a dictionary, where key is the fixture name and
 value is the path to the hosts in the form: ``$domain-id.$role[$index]``. This
 will point to a role object of a specific host from the configuration file. It
 is also possible to reference a group of hosts by omitting the index:
@@ -189,7 +189,7 @@ KnownTopology and KnownTopologyGroup
 ------------------------------------
 
 This is kind of pre-defined topology, that groups multiple topologies in a
-single :class:`~enum.Enum` class. This makes it little bit easier to use then
+single :class:`~enum.Enum` class. This makes it a little bit easier to use than
 ungrouped :ref:`pre-defined topologies <predefined_topology>`, since you only
 have to import one object to your test module and you get access to all
 topologies -- you do not have to import each topology separately.
@@ -254,8 +254,8 @@ list of topologies for :ref:`topology parametrization
 Extending Topology Marker
 -------------------------
 
-The topology marker can be extended in order to provide more parameters or
-additional functionality. In order to do this, subclass
+The topology marker can be extended to provide more parameters or additional
+functionality. In order to do this, subclass
 :class:`~pytest_mh.TopologyMark` and override
 :meth:`~pytest_mh.TopologyMark.CreateFromArgs` and
 :meth:`~pytest_mh.TopologyMark.export`.
@@ -415,9 +415,9 @@ thus quickly extend the code coverage. Pytest allows this by using the
 ``@pytest.mark.parametrize`` `mark <pytest-parametrize_>`_.
 
 Similar functionality can be achieved with topologies when the same test code is
-run against multiple topologies. This is useful for many situations, since it is
+run against multiple topologies. This is useful for many situations, as it is
 often desirable to test the same functionality with different configurations
-that however also requires different environment setup (different multihost
+which, however, also require a different environment setup (different multihost
 topology). For example:
 
 * A client application is able to connect to multiple different backends. This
@@ -433,9 +433,9 @@ 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 only single test that is however 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 have multiple topologies
+In each case, it is desirable to have a single test which, however, 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.
 
 .. tab-set::
@@ -593,7 +593,8 @@ generic type ``GenericProvider`` that is implemented by the individual backends.
 .. note::
 
     Notice that SSSD is using custom topology marker ``SSSDTopologyMark`` that
-    adds a custom ``domains`` property. You can see its definition `here <sssd_framework_mark_>`_.
+    adds a custom ``domains`` property. You can see its definition
+    `here <sssd_framework_mark_>`_.
 
 If we run the test, we can see that it is executed four times:
 

docs/articles/extending/multihost-utilities.rst

@@ -137,8 +137,8 @@ cleans up after itself and share this code between multiple roles.
 
     In theory, it is possible, if you know what you are doing and call setup and
     teardown manually at desired place. However, it is not possible to call
-    these methods multiple times and so you can only use it within a single
-    setup scope. It is therefore highly recommended to only use
+    these methods multiple times, so you can only use it within a single setup
+    scope. It is therefore highly recommended to only use
     :class:`~pytest_mh.MultihostReentrantUtility` in host objects.
 
 MultihostReentrantUtility
@@ -149,7 +149,8 @@ setup scopes. Therefore, if you change something during topology setup, it is
 reverted in topology teardown and so on. It is also possible to create different
 setup scopes inside a test by using a context manager or the ``with`` statement.
 
-In order to achieve this, they gain context management magic methods
+In order to achieve this, :class:`~pytest_mh.MultihostReentrantUtility`
+gains context management magic methods
 :meth:`~pytest_mh.MultihostReentrantUtility.__enter__` and
 :meth:`~pytest_mh.MultihostReentrantUtility.__exit__`. The reentrant utilities
 are setup once and then the enter is called every time a new scope is entered.

docs/articles/get-started.rst

@@ -29,11 +29,11 @@ application.
     and read it side by side.**
 
 We will use `sudo <https://www.sudo.ws/>`__ as the application to test for this
-getting started guide as sudo is known by every power user so changes are that
+getting started guide as sudo is known by every power user so chances are that
 you are already familiar with it. Additionally, sudo tests allows us to show
 many pytest-mh features. Note, that these tests were written only as an example
-and sudo itself is not using pytest-mh for its tests at this moment and there
-are no plans to do so.
+and sudo itself is not using pytest-mh for its tests at this moment and as far
+as we know there are no plans to do so.
 
 .. seealso::
 
@@ -55,10 +55,12 @@ Our goals are:
 
 * write basic tests
 
-  * allow user run all commands, user must authenticate
-  * allow user run all commands, without authentication
-  * allow user run all commands if he or she is a member of a group, user must authenticate
-  * allow user run all commands if he or she is a member of a group, without authentication
+  * allow the user to run all commands, user must authenticate
+  * allow the user to run all commands, without authentication
+  * allow the user to run all commands if they are a member of a group, user
+  must authenticate
+  * allow the user to run all commands if they are a member of a group, without
+  authentication
 
 * these tests must be written for all possible sources of data
 
@@ -72,7 +74,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 for tests but run them against
+parametrization will allow 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:
@@ -127,9 +129,9 @@ Define multihost topologies
 ---------------------------
 
 This is the first step when designing a test framework since it tells you what
-hosts and roles your project needs. For sudo, we want to that that the sudo
-rules can be fetched from different sources. We can consider each data source to
-be a single topology.
+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**
 
@@ -147,7 +149,7 @@ be a single topology.
   * we need a host where we will run sudo and SSSD and a host that runs an LDAP server
   * SSSD will be connected to the LDAP domain
   * users, groups and sudo rules will be added to the LDAP database
-  * sudo will read data from SSSD which reads it from LDAP
+  * sudo will read data from SSSD which in turn reads it from LDAP
 
 These are the three topologies that we will define. We will also define a
 topology group as a shortcut for :ref:`topology parametrization
@@ -169,7 +171,7 @@ topology group as a shortcut for :ref:`topology parametrization
 Write configuration file
 ------------------------
 
-The topologies 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 test. 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``
@@ -219,8 +221,8 @@ Design and implement the framework
 ----------------------------------
 
 This part is rather more complicated and can not be treated universally as every
-project have different needs. It is possible to use multiple building block
-provided by pytest-mh in order to built a high-level API for your tests, see
+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
 :doc:`extending` and :doc:`life-cycle` to get a good grasp of all the classes
 and how to use them.
 
@@ -252,7 +254,7 @@ main idea behind each of these classes.
                 | :class:`~pytest_mh.BackupTopologyController`
               - * Configures environment for the sudoers topology
                 * Sets expected content of ``/etc/nsswitch.conf``
-                * Creates backup of this setup and automatically restores to this
+                * Creates backup of this setup and automatically restores its
                   state when a test is finished
 
             * - | ``LDAPTopologyController``
@@ -261,15 +263,15 @@ main idea behind each of these classes.
                 * Sets expected content of ``/etc/nsswitch.conf``
                 * Configures SSSD for identity and authentication
                 * Configures ``/etc/ldap.conf`` that is read by sudo
-                * Creates backup of this setup and automatically restores to this
+                * Creates backup of this setup and automatically restores its
                   state when a test is finished
 
             * - | ``SSSDTopologyController``
                 | :class:`~pytest_mh.BackupTopologyController`
               - * Configures environment for the SSSD topology
                 * Sets expected content of ``/etc/nsswitch.conf``
                 * Configures SSSD for identity, authentication and sudo rules
-                * Creates backup of this setup and automatically restores to this
+                * Creates backup of this setup and automatically restores its
                   state when a test is finished
 
             * - | ``Client``
@@ -306,9 +308,9 @@ main idea behind each of these classes.
 Enable pytest-mh in conftest.py
 -------------------------------
 
-When the test framework is written and read 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.
+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.
 
 .. dropdown:: See the code
     :color: primary
@@ -327,14 +329,16 @@ Write the tests
 ===============
 
 The example code shows four tests in total, but 12 tests are executed when
-pytest is run because each test is run once per each topology against different
-data source. See :doc:`writing-tests` to get more information on how to write
+pytest is run because each test is run once per topology against different data
+sources. See :doc:`writing-tests` to get more information on how to write
 the tests.
 
-  * allow user run all commands, user must authenticate
-  * allow user run all commands, without authentication
-  * allow user run all commands if he or she is a member of a group, user must authenticate
-  * allow user run all commands if he or she is a member of a group, without authentication
+  * allow the user to run all commands, user must authenticate
+  * allow the user to run all commands, without authentication
+  * allow the user to run all commands if they are a member of a group, user
+  must authenticate
+  * allow the user to run all commands if they are a member of a group, without
+  authentication
 
 .. dropdown:: See the code
     :color: primary
@@ -356,15 +360,14 @@ the tests.
 
 Run the tests
 =============
-
-The example code provides a set of containers that can be started up and used as
-hosts for the tests. See the example `readme.md
+The example code provides a set of containers that can be started and used as
+hosts for testing. See the example `readme.md
 <https://github.com/next-actions/pytest-mh/tree/master/example/readme.md>`__ to
 get the instruction on how to start the containers and install requirements.
 
 When the containers or virtual machines are ready, it is possible to run the
-tests with ``pytest`` command that you are already familiar with. The only
-additional thing needed to run pytest-mh tests is to provide path to the
+tests with the ``pytest`` command that you are already familiar with. The only
+additional thing needed to run pytest-mh tests is to provide the path to the
 pytest-mh configuration file with ``--mh-config``.
 
 .. code-block:: text