Spell and grammar checking for more docs. (#281)

Author: tobiasraabe

docs/source/developers_guide.md

@@ -1,5 +1,17 @@
 # Developer's Guide
 
+## Testing
+
+Run pytest to execute the test suite.
+
+The test suite creates many temporary directories. There is usually a limit on the
+number of open file descriptors on Unix systems which causes some tests and the end of
+the test suite to fail. If that happens, increase the limit with the following command.
+
+```console
+$ ulimit -n 4096
+```
+
 ## How to release
 
 The following list covers all steps of a release cycle.

docs/source/explanations/pluggy.md

@@ -5,15 +5,15 @@
 pluggy ([^id4], [^id5], [^id6]) is at the heart of pytask and enables its plugin system.
 The mechanism to achieve extensibility is called {term}`hooking`.
 
-At certain points, pytask, or more generally the host, implements entry-points which are
-called hook specifications. At these entry-points the host sends a message to all
-plugins which target this entry-point. The recipient of the message is implemented by
-the plugin and called a hook implementation. The hook implementation receives the
-message and can decide whether to send a response or not. Then, the host receives the
-responses and can decide whether to process all or just the first valid return.
+At specific points, pytask, or more generally the host, implements entry-points called
+hook specifications. At these entry-points, the host sends a message to all plugins
+which target this entry-point. The message's recipient is implemented by the plugin and
+called a hook implementation. The hook implementation receives the message and can
+decide whether to send a response or not. Then, the host gets the responses and can
+choose whether to process all or just the first valid return.
 
 In contrast to some other mechanisms to change the behavior of a program (like method
-overriding, monkey patching), hooking excels at allowing multiple plugins to work
+overriding and monkey patching), hooking excels at allowing multiple plugins to work
 alongside each other.
 
 It is the host's responsibility to design the entry-points in a way such that
@@ -22,7 +22,7 @@ It is the host's responsibility to design the entry-points in a way such that
   goal efficiently.
 - many plugins can work alongside each other.
 - the necessary knowledge about pytask to implement a plugin is somewhat proportional to
-  the complexity of plugin's provided functionality.
+  the complexity of the plugin's provided functionality.
 
 ## References
 

docs/source/explanations/why_pytask.md

@@ -1,6 +1,6 @@
 # Why pytask?
 
-There are a lot of workflow management systems out there with existing communities who
+There are a lot of workflow management systems out there with existing communities that
 accumulated a lot of experience over time. So why bother creating another workflow
 management system?
 
@@ -11,23 +11,24 @@ provide a [steep learning curve](https://english.stackexchange.com/a/6226).
 
 pytask tries to address this point in many ways.
 
-1. pytask is written in Python which is one of the most popular and fastest growing
-   languages in the realm of scientific computing.
+1. pytask is written in Python, one of the most popular and fastest growing languages in
+   scientific computing.
 
-1. For those who know pytest, the main testing framework in Python, pytask will look
-   extremely familiar and you will feel productive quickly. If you do not know pytest,
-   you will learn two tools at the same time.
+1. For those who know pytest, the primary testing framework in Python, pytask will look
+   highly familiar, and you will feel productive quickly. If you do not know pytest, you
+   will learn two tools simultaneously.
 
 1. pytask tries to improve your productivity by offering a couple of features like
    {doc}`repeating tasks <../tutorials/repeating_tasks_with_different_inputs>`,
    {doc}`debugging of tasks <../tutorials/debugging>` and
    {doc}`selecting subsets of tasks <../tutorials/selecting_tasks>`.
 
-1. pytask integrates with other tools which are used in the scientific community such as
-   R and Julia and offers solutions to bridge the gap between a
-   {term}`workflow management system` written in Python and scripts in another language,
-   for example, by making paths to dependencies and products usable in the scripts.
+1. pytask integrates with other tools used in the scientific community, such as R and
+   Julia, and offers solutions to bridge the gap between a
+   {term}`workflow management system` written in Python and scripts in another language.
+   For example, pytask makes paths to dependencies and products available in the
+   scripts.
 
-1. The plugin system let's power users tailor pytask to their needs by adding additional
-   functionality. It makes pytask extremely versatile and offers people from different
-   backgrounds to collaborate on the same software.
+1. The plugin system lets power users tailor pytask to their needs by adding additional
+   functionality. It makes pytask extraordinarily versatile and offers people from
+   different backgrounds to collaborate on the same software.

docs/source/how_to_guides/bp_scalable_repititions_of_tasks.md renamed to docs/source/how_to_guides/bp_scalable_repetitions_of_tasks.md

@@ -1,28 +1,27 @@
-# Scalable repititions of tasks
+# Scalable repetitions of tasks
 
-This section gives advice on how to use repitions to quickly scale your project.
+This section advises on how to use repetitions to scale your project quickly.
 
 ## TL;DR
 
-- Loop over dictionaries which map ids to `kwargs` to create multiple tasks.
+- Loop over dictionaries that map ids to `kwargs` to create multiple tasks.
 - Create the dictionary with a separate function.
 - Create functions to build intermediate objects like output paths which can be shared
   more easily across tasks than the generated values.
 
 ## Scalability
 
-Parametrizations allow to scale tasks from $1$ to $N$ in a simple way. What is easily
+Parametrizations allow scaling tasks from $1$ to $N$ in a simple way. What is easily
 overlooked is that parametrizations usually trigger other parametrizations and the
 growth in tasks is more $1$ to $N \cdot M \cdot \dots$ or $1$ to $N^{M \cdot \dots}$.
 
-To keep the resulting complexity as manageable as possible, this guide lays out a
-structure which is simple, modular, and scalable.
+This guide lays out a simple, modular, and scalable structure to fight complexity.
 
-As an example, assume we have four datasets with one binary dependent variables and some
-independent variables. On each of the data sets, we fit three models, a linear model, a
-logistic model, and a decision tree. In total, we have $4 \cdot 3 = 12$ tasks.
+For example, assume we have four datasets with one binary dependent variable and some
+independent variables. We fit three models on each data set: a linear model, a logistic
+model, and a decision tree. In total, we have $4 \cdot 3 = 12$ tasks.
 
-First, let us take a look at the folder and file structure of such a project.
+First, let us look at the folder and file structure of such a project.
 
 ```
 my_project
@@ -56,12 +55,12 @@ my_project
 └───bld
 ```
 
-The folder structure, the main `config.py` which holds `SRC` and `BLD` and the tasks
-follow the same structure which is advocated for throughout the tutorials.
+The folder structure, the main `config.py` which holds `SRC` and `BLD`, and the tasks
+follow the same structure advocated throughout the tutorials.
 
-What is new are the local configuration files in each of the subfolders of `my_project`
-which contain objects which are shared across tasks. For example, `config.py` holds the
-paths to the processed data and the names of the data sets.
+What is new are the local configuration files in each subfolder of `my_project`, which
+contain objects shared across tasks. For example, `config.py` holds the paths to the
+processed data and the names of the data sets.
 
 ```python
 # Content of config.py
@@ -81,8 +80,7 @@ def path_to_processed_data(name):
     return BLD / "data" / f"processed_{name}.pkl"
 ```
 
-In the task file `task_prepare_data.py`, these objects are used to build the
-parametrization.
+The task file `task_prepare_data.py` uses these objects to build the parametrization.
 
 ```python
 # Content of task_prepare_data.py
@@ -115,8 +113,8 @@ for id_, kwargs in _ID_TO_KWARGS.items():
 ```
 
 All arguments for the loop and the {func}`@pytask.mark.task <pytask.mark.task>`
-decorator are built within a function to keep the logic in one place and the namespace
-of the module clean.
+decorator is built within a function to keep the logic in one place and the module's
+namespace clean.
 
 Ids are used to make the task {ref}`ids <ids>` more descriptive and to simplify their
 selection with {ref}`expressions <expressions>`. Here is an example of the task ids with
@@ -152,15 +150,15 @@ def path_to_estimation_result(name):
 ```
 
 In the local configuration, we define `ESTIMATIONS` which combines the information on
-data and model. The key of the dictionary can be used as a task id whenever the
-estimation is involved. This allows to trigger all tasks related to one estimation -
-estimation, figures, tables - with one command
+data and model. The dictionary's key can be used as a task id whenever the estimation is
+involved. It allows triggering all tasks related to one estimation - estimation,
+figures, tables - with one command.
 
 ```console
 pytask -k linear_probability_data_0
 ```
 
-And, here is the task file.
+And here is the task file.
 
 ```python
 # Content of task_estimate_models.py
@@ -198,13 +196,11 @@ for id_, kwargs in _ID_TO_KWARGS.items():
             ...
 ```
 
-Replicating this pattern across a project allows for a clean way to define
-parametrizations.
+Replicating this pattern across a project allows a clean way to define parametrizations.
 
 ## Extending parametrizations
 
-Some parametrized tasks are extremely expensive to run - be it in terms of computing
-power, memory or time. On the other hand, parametrizations are often extended which
-could also trigger all parametrizations to be rerun. Thus, use the
-{func}`@pytask.mark.persist <pytask.mark.persist>` decorator which is explained in more
-detail in this {doc}`tutorial <../tutorials/making_tasks_persist>`.
+Some parametrized tasks are costly to run - costly in terms of computing power, memory,
+or time. Users often extend parametrizations triggering all parametrizations to be
+rerun. Thus, use the {func}`@pytask.mark.persist <pytask.mark.persist>` decorator, which
+is explained in more detail in this {doc}`tutorial <../tutorials/making_tasks_persist>`.

docs/source/how_to_guides/index.md

@@ -36,5 +36,5 @@ maxdepth: 1
 bp_structure_of_a_research_project
 bp_structure_of_task_files
 bp_templates_and_projects
-bp_scalable_repititions_of_tasks
+bp_scalable_repetitions_of_tasks
 ```

docs/source/how_to_guides/repeating_tasks_with_different_inputs_the_pytest_way.md

@@ -1,31 +1,28 @@
 # Repeating tasks with different inputs - The pytest way
 
-You want to define a task which should be repeated over a range of inputs? Loop over
-your task function!
-
-:::{hint}
-The process of repeating a function with different inputs is called parametrizations.
-:::
-
 :::{important}
 This guide shows you how to parametrize tasks with the pytest approach. For the new and
 preferred approach, see this
 {doc}`tutorial <../tutorials/repeating_tasks_with_different_inputs>`.
 :::
 
-You want to define a task which should be repeated over a range of inputs? Parametrize
+Do you want to define a task repeating an action over a range of inputs? Parametrize
 your task function!
 
+:::{hint}
+The process of repeating a function with different inputs is called parametrizations.
+:::
+
 :::{seealso}
 If you want to know more about best practices for parametrizations, check out this
-{doc}`guide <../how_to_guides/bp_scalable_repititions_of_tasks>` after you made yourself
-familiar this tutorial.
+{doc}`guide <../how_to_guides/bp_scalable_repititions_of_tasks>` after you have made
+yourself familiar with this tutorial.
 :::
 
 ## An example
 
-We reuse the previous example of a task which generates random data and repeat the same
-operation over a number of seeds to receive multiple, reproducible samples.
+We reuse the previous example of a task that generates random data and repeat the same
+operation over some seeds to receive multiple, reproducible samples.
 
 First, we write the task for one seed.
 
@@ -61,12 +58,12 @@ specifies the name of a task function argument.
 The signature is explained in detail {ref}`below <parametrize-signature>`.
 :::
 
-The second argument of the parametrize decorator is a list (or any iterable) which has
-as many elements as there are iterations over the task function. Each element has to
-provide one value for each argument name in the signature - two in this case.
+The second argument of the parametrize decorator is a list with one element per
+iteration. Each element must provide one value for each argument name in the signature -
+two in this case.
 
-Putting all together, the task is executed three times and each run the path from the
-list is mapped to the argument `produces` and `seed` receives the seed.
+pytask executes the task function three times and passes the path from the list to the
+argument `produces` and the seed to `seed`.
 
 :::{note}
 If you use `produces` or `depends_on` in the signature of the parametrize decorator, the
@@ -77,7 +74,7 @@ values are handled as if they were attached to the function with
 
 ## Un-parametrized dependencies
 
-To specify a dependency which is the same for all parametrizations, add it with
+To specify a dependency that is the same for all parametrizations, add it with
 {func}`@pytask.mark.depends_on <pytask.mark.depends_on>`.
 
 ```python
@@ -95,10 +92,10 @@ def task_create_random_data(seed, produces):
 
 ## The signature
 
-The signature can be passed in three different formats.
+pytask allows for three different kinds of formats for the signature.
 
-1. The signature can be a comma-separated string like an entry in a csv table. Note that
-   white-space is stripped from each name which you can use to separate the names for
+1. The signature can be a comma-separated string like an entry in a CSV table. Note that
+   white space is stripped from each name which you can use to separate the names for
    readability. Here are some examples:
 
    ```python
@@ -114,41 +111,41 @@ The signature can be passed in three different formats.
    ("first_argument", "second_argument")
    ```
 
-1. Finally, it is also possible to use a list of strings.
+1. Finally, using a list of strings is also possible.
 
    ```python
    ["first_argument", "second_argument"]
    ```
 
 ## The id
 
-Every task has a unique id which can be used to
-{doc}`select it <../tutorials/selecting_tasks>`. The normal id combines the path to
-the module where the task is defined, a double colon, and the name of the task function.
+Every task has a unique id that can be used to
+{doc}`select it <../tutorials/selecting_tasks>`. The normal id combines the path to the
+module where the task is defined, a double colon, and the name of the task function.
 Here is an example.
 
 ```
 ../task_example.py::task_example
 ```
 
 This behavior would produce duplicate ids for parametrized tasks. Therefore, there exist
-multiple mechanisms to produce unique ids.
+multiple mechanisms to have unique ids.
 
 (auto-generated-ids)=
 
 ### Auto-generated ids
 
-To avoid duplicate task ids, the ids of parametrized tasks are extended with
-descriptions of the values they are parametrized with. Booleans, floats, integers and
-strings enter the task id directly. For example, a task function which receives four
-arguments, `True`, `1.0`, `2`, and `"hello"`, one of each dtype, has the following id.
+pytask construct ids by extending the task name with representations of the values used
+for each iteration. Booleans, floats, integers, and strings enter the task id directly.
+For example, a task function that receives four arguments, `True`, `1.0`, `2`, and
+`"hello"`, one of each dtype, has the following id.
 
 ```
 task_example.py::task_example[True-1.0-2-hello]
 ```
 
-Arguments with other dtypes cannot be easily converted to strings and, thus, are
-replaced with a combination of the argument name and the iteration counter.
+Arguments with other dtypes cannot be converted to strings and, thus, are replaced with
+a combination of the argument name and the iteration counter.
 
 For example, the following function is parametrized with tuples.
 
@@ -192,10 +189,10 @@ task_example.py::task_example[second]  # (1,)
 To change the representation of tuples and other objects, you can pass a function to the
 `ids` argument of the {func}`@pytask.mark.parametrize <pytask.mark.parametrize>`
 decorator. The function is called for every argument and may return a boolean, number,
-or string which will be integrated into the id. For every other return, the
+or string, which will be integrated into the id. For every other return, the
 auto-generated value is used.
 
-To get a unique representation of a tuple, we can use the hash value.
+We can use the hash value to get a unique representation of a tuple.
 
 ```python
 def tuple_to_hash(value):
@@ -208,7 +205,7 @@ def task_example(i):
     pass
 ```
 
-This produces the following ids:
+The tasks have the following ids:
 
 ```
 task_example.py::task_example[3430018387555]  # (0,)