Updated documentation and README

README.rst

@@ -26,8 +26,8 @@ Glossary
 ++++++++
 
 * **Arca** - name of the library. When written as ``Arca``, the main interface class is being referenced.
-* **Backend** - a way of running tasks
 * **Task** - definition of the script, consists of a reference to a callable object and arguments.
+* **Backend** - a way of running tasks.
 
 Installation
 ++++++++++++
@@ -58,15 +58,15 @@ Or if you wish to install the upstream version:
 
   python -m pip install git+https://github.com/mikicz/arca.git#egg=arca
 
-Hello World example
-+++++++++++++++++++
+Example
++++++++
 
 To run a Hello World example you'll only need the ``arca.Arca`` and ``arca.Task`` classes.
 ``Task`` is used for defining the task that's supposed to be run in the repositories.
-``Arca`` takes care of all the settings and provides the basic API for running tasks.
+``Arca`` takes care of all the settings and provides the basic API for running the tasks.
 
-Let's imagine we have the following file, called ``hello_world.py``, in a repository ``https://example.com/hello_word.git``,
-on branch ``master``.
+Let's day we have the following file, called ``hello_world.py``,
+in a repository ``https://example.com/hello_word.git``, on branch ``master``.
 
 .. code-block:: python
 
@@ -85,13 +85,13 @@ To call the function using Arca, the following example would do so:
   result = arca.run("https://example.com/hello_word.git", "master", task)
   print(result.output)
 
-The code would print ``Hello World!``. ``result`` would be a ``arca.Result`` instance which currently only has one
-attribute ``output`` with the output of the function call.
-If the task failed, ``arca.exceptions.BuildError`` would be raised.
+The code would print ``Hello World!``.
+``result`` would be a ``arca.Result`` instance which currently only has one attribute,
+``output``, with the output of the function call.
+If the task fails, ``arca.exceptions.BuildError`` would be raised.
 
-By default, the `Current Environment Backend <https://arca.readthedocs.io/en/latest/backends.html#current-environment>`_
-is used to run tasks, which uses the python installation which is used to run
-Arca, launching the code in a subprocess. You can learn about backends `here <https://arca.readthedocs.io/en/latest/backends.html>`_.
+By default, the `Current Environment Backend <https://arca.readthedocs.io/en/latest/backends.html#current-environment>`_ is used to run tasks,
+which uses the current Python, launching the code in a subprocess. You can learn about backends `here <https://arca.readthedocs.io/en/latest/backends.html>`_.
 
 Further reading
 ***************

docs/backends.rst

@@ -24,7 +24,7 @@ or environ variables.
 
 Setting up backends is based on the same principle as setting up :class:`Arca <arca.Arca>`.
 You can either pass keyword arguments when initializing the backend class
-or you can use settings (described in more details in :ref:`configuring`. For example these two calls are equivalent:
+or you can use settings (described in more details in :ref:`configuring`). For example these two calls are equivalent:
 
 .. code-block:: python
 

docs/cookbook.rst

@@ -6,14 +6,12 @@ Cookbook
 I need some files from the repositories
 ---------------------------------------
 
-Let's say there are some files in the repository that you need for something,
-for example a image ``images/example.png`` from the branch ``master`` of ``https://example.com/hello_word.git``.
-
-With the :class:`Arca <arca.Arca>` method :meth:`static_filename <arca.Arca.static_filename>`
+Besides running scripts from the repositories, there also might be some files in the repositories that you need,
+e.g. images for a webpage. With the :class:`Arca <arca.Arca>` method :meth:`static_filename <arca.Arca.static_filename>`
 you can get the absolute path to that file, to where Arca cloned it.
 The method accepts a relative path (can be a :class:`pathlib.Path` or :class:`str`) to the file in the repository.
 
-Example call:
+Example call (file ``images/example.png`` from the branch ``master`` of ``https://example.com/hello_word.git``):
 
 .. code-block:: python
 
@@ -31,18 +29,21 @@ leads out of the repo, :class:`FileOutOfRangeError <arca.exceptions.FileOutOfRan
 I will be running a lot of tasks from the same repository
 ---------------------------------------------------------
 
-This might be useful for example if you're building a static page from the repository and
-you want to speed things up. Arca has some overhead for each launched task, but it can be sped up using the following
-two ways:
+Similarly as above, while you're building a webpage you might need to run a lot of tasks from the same repositories,
+to render all the individual pages. However Arca has some overhead for each launched task, but these two
+options can speed things up:
 
 Singe pull
 ++++++++++
 
 This option ensures that each branch is only cloned/pulled once per initialization of :class:`Arca <arca.Arca>`.
 You can set it up with the :class:`Arca <arca.Arca>` ``single_pull`` option (``ARCA_SINGLE_PULL`` setting).
+This doesn't help to speedup the first task from a repository, however each subsequent will run faster.
+This setting is quite useful for keeping consistency, since the state of the repository can't change in the middle
+of running multiple tasks.
 
 You can tell :class:`Arca <arca.Arca>` to pull again (if a task from that repo/branch is called again)
-by calling the method :meth:`Arca.pull_again <arca.Arca.pull_again>`.
+by calling the method :meth:`Arca.pull_again <arca.Arca.pull_again>`:
 
 .. code-block:: python
 

docs/quickstart.rst

@@ -7,20 +7,20 @@ Glossary
 .. remember to update README when updating this
 
 * **Arca** - name of the library. When written as :class:`Arca <arca.Arca>`, the main interface class is being referenced.
-* **Backend** - a way of running tasks
 * **Task** - definition of the script, consists of a reference to a callable object and arguments.
+* **Backend** - a way of running tasks.
 
-Hello World example
--------------------
+Example
+-------
 
 .. remember to update README when updating this
 
 To run a Hello World example you'll only need the :class:`arca.Arca` and :class:`arca.Task` classes.
 :class:`Task <arca.Task>` is used for defining the task that's supposed to be run in the repositories.
-:class:`Arca <arca.Arca>` takes care of all the settings and provides the basic API for running tasks.
+:class:`Arca <arca.Arca>` takes care of all the settings and provides the basic API for running the tasks.
 
-Let's imagine we have the following file, called ``hello_world.py``, in a repository ``https://example.com/hello_word.git``,
-on branch ``master``.
+Let's say we have the following file, called ``hello_world.py``,
+in a repository ``https://example.com/hello_word.git``, on branch ``master``.
 
 .. code-block:: python
 
@@ -39,9 +39,10 @@ To call the function using Arca, the following example would do so:
   result = arca.run("https://example.com/hello_word.git", "master", task)
   print(result.output)
 
-The code would print ``Hello World!``. ``result`` would be a :class:`Result <arca.Result>` instance which currently only has one
-attribute ``output`` with the output of the function call.
-If the task failed, :class:`arca.exceptions.BuildError` would be raised.
+The code would print ``Hello World!``.
+``result`` would be a :class:`Result <arca.Result>` instance which currently only has one attribute,
+``output``, with the output of the function call.
+If the task fails, :class:`arca.exceptions.BuildError` would be raised.
 
-By default, the :ref:`Current Environment Backend <backends_cur>` is used to run tasks, which uses the python installation which is used to run
-Arca, launching the code in a subprocess. You can learn about backends :ref:`here <backends>`.
+By default, the :ref:`Current Environment Backend <backends_cur>` is used to run tasks,
+which uses the current Python, launching the code in a subprocess. You can learn about backends :ref:`here <backends>`.

docs/settings.rst

@@ -59,12 +59,12 @@ where the files should be stored. The default is ``.arca``. If the folder doesn'
 **backend** (`ARCA_BACKEND`)
 
 This options tells how the tasks should be launched. This setting can be provided as a string, a class or a instance.
-The default is ``arca.CurrentEnvironmentBackend``, the :ref:`backends_cur` Backend.
+The default is ``arca.CurrentEnvironmentBackend``, the :ref:`Current Environment Backend <backends_cur>`.
 
 Backends
 ++++++++
 
-This section describes settings that are common for all backends.
+This section describes settings that are common for all the backends.
 
 **requirements_location** (`ARCA_BACKEND_REQUIREMENTS_LOCATION`)
 
@@ -73,5 +73,5 @@ to ``None`` to indicate there are no requirements. The default is ``requirements
 
 **cwd** (`ARCA_BACKEND_CWD`)
 
-Tells in what working directory the tasks should be launched. Also a relative path.
+Tells Arca in what working directory the tasks should be launched, so again a relative path.
 The default is the root of the repository.