Updated some documentation, filled up README.rst, setup docs version

.readthedocs.yml

@@ -1,5 +1,4 @@
 build:
   image: latest
 python:
-  setup_py_install: true
   version: 3.6

README.rst

@@ -13,6 +13,9 @@ Arca
 .. image:: https://img.shields.io/github/license/mikicz/arca.svg?style=flat
    :target: https://github.com/mikicz/arca/blob/master/LICENSE
 
+.. image:: https://img.shields.io/readthedocs/arca.svg
+   :target: https://arca.readthedocs.io/
+
 Arca is a library for running Python scripts from git repositories in various states of isolation.
 Arca can also cache the results of these scripts using `dogpile.cache <https://dogpilecache.readthedocs.io/en/latest/>`_.
 
@@ -22,16 +25,76 @@ Getting started
 Glossary
 ++++++++
 
+* **Arca** - name of the library. When written as :class:`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.
+
 Installation
 ++++++++++++
 
+Requirements
+------------
+
+* Python >= 3.6
+
+Requirements for certain backends:
+
+* `Docker <https://www.docker.com/>`_ (for :ref:`Docker Backend <backends_doc>` and :ref:`Vagrant Backend <backends_vag>`)
+* `Vagrant <https://www.vagrantup.com/>`_ (for the :ref:`Vagrant Backend <backends_vag>`)
+
+Installation
+------------
+
+To install the last stable version:
+
+.. code-block:: bash
+
+  python -m pip install arca
+
+Or if you wish to install the upstream version:
+
+.. code-block:: bash
+
+  python -m pip install git+https://github.com/mikicz/arca.git#egg=arca
+
 Hello World example
 +++++++++++++++++++
 
+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.
+
+Let's imagine we have the following file, called ``hello_world.py``, in a repository ``https://example.com/hello_word.git``,
+on branch ``master``.
+
+.. code-block:: python
+
+  def say_hello():
+     return "Hello World!"
+
+To call the function using Arca, the following example would do so:
+
+.. code-block:: python
+
+  from arca import Arca, Task
+
+  task = Task("hello_world:say_hello")
+  arca = Arca()
+
+  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.
+
+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>`.
+
 Further reading
 ***************
 
-You can read the full documentation on `Read The Docs <http://arca.readthedocs.io/en/latest/>`_.
+You can read the full documentation on `Read The Docs <https://arca.readthedocs.io/>`_.
 
 Running tests
 **************

docs/backends.rst

@@ -5,7 +5,7 @@ Backends
 
 There are currently four different backends. They can also be initialized in few different ways,
 consistent with general settings. You can use the ``ARCA_BACKEND`` setting
-or you can pass a ``backend`` keyword directly to ``Arca``.
+or you can pass a ``backend`` keyword directly to :class:`Arca <arca.Arca>`.
 
 The backend setting can be either a string, class or an instance. All the initializations shown bellow are equivalent,
 but again, as mentioned in :ref:`configuring`, the ``backend`` keyword cannot be overridden by settings
@@ -22,7 +22,7 @@ or environ variables.
   Arca(backend=DockerBackend())
 
 
-Setting up backends is based on the same principle as setting up ``Arca``.
+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:
 
@@ -61,7 +61,7 @@ There are two settings for this backend, to determine how the backend should tre
 Requirements strategies:
 ++++++++++++++++++++++++
 
-The strategies are defined in a enum, ``arca.RequirementsStrategy``. Its values or the string representation can be
+The strategies are defined in a enum, ``arca.RequirementsStrategy``. Its values or the string representations can be
 used in settings.
 
 * ``raise``, ``RequirementsStrategy.RAISE``:
@@ -80,7 +80,7 @@ Virtual Environment
 This backend uses the Python virtual environments to run the tasks. The environments are created from the Python
 used to run Arca and they are shared between repositories that have the same exact requirement file.
 The virtual environments are stored in folder ``venv`` in folder
-determined by the ``Arca`` ``base_dir`` setting, usually ``.arca``.
+determined by the :class:`Arca <arca.Arca>` ``base_dir`` setting, usually ``.arca``.
 
 (possible settings prefixes: ``ARCA_VENV_BACKEND_`` and ``ARCA_BACKEND_``)
 
@@ -155,7 +155,7 @@ for ``keep_container_running`` and has these extra settings:
 * **provider**: Vagrant provider, default is ``virtualbox``.
   Visit `vagrant docs <https://www.vagrantup.com/docs/providers/>`_ for more.
 * **quiet**: Tells Vagrant and Fabric (which is used to run the task in the VM) to be quiet. Default is ``True``.
-  Vagrant and Docker output is logged in separate files for each run in a folder ``logs`` in the ``Arca`` ``base_dir``.
+  Vagrant and Docker output is logged in separate files for each run in a folder ``logs`` in the :class:`Arca <arca.Arca>` ``base_dir``.
   The filename is logged in the arca logger (see bellow)
 * **destroy**: Destroy the VM right after the task is finished if ``True`` (default).
   If ``False`` is set, the VM is only halted.
@@ -165,5 +165,5 @@ for ``keep_container_running`` and has these extra settings:
 Your own
 --------
 
-You can also create your own backend and pass it to ``Arca``. It has be a subclass of ``arca.backend.base.BaseBackend`` and
-it has to implement its ``run`` method.
+You can also create your own backend and pass it to :class:`Arca <arca.Arca>`. It has be a subclass of :class:`arca.BaseBackend` and
+it has to implement its :meth:`run <arca.BaseBackend.run>` method.

docs/caching.rst

@@ -26,7 +26,7 @@ To see all available cache backends and their settings,
 please visit the ``dogpile.cache`` `documentation <https://dogpilecache.readthedocs.io/en/latest/>`_.
 Some of the other backends might have other python dependencies.
 
-When ``Arca`` is being initialized, a check is made if the cache backend is writable and readable,
-which raises an ``arca.exceptions.ArcaMisconfigured`` if it's not.
+When :class:`Arca <arca.Arca>` is being initialized, a check is made if the cache backend is writable and readable,
+which raises an :class:`arca.exceptions.ArcaMisconfigured` if it's not.
 If the cache requires some python dependency :class:`ModuleNotFoundError` will be raised.
 If you wish to ignore these errors, ``ignore_cache_errors`` setting can be used.

docs/conf.py

@@ -16,17 +16,18 @@
 import sys
 sys.path.insert(0, os.path.abspath('../'))
 
+import arca
+
 # -- Project information -----------------------------------------------------
 
 project = 'Arca'
 copyright = '2017 - 2018, Mikuláš Poul'
 author = 'Mikuláš Poul'
 
 # The short X.Y version
-version = ''
+version = arca.__version__.rsplit(".", 1)[0]
 # The full version, including alpha/beta/rc tags
-release = ''
-
+release = arca.__version__
 
 # -- General configuration ---------------------------------------------------
 

docs/cookbook.rst

@@ -7,10 +7,11 @@ 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``.
+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 ``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 ``pathlib.Path`` or ``str``) to the file in the repository.
+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:
 
@@ -30,8 +31,9 @@ leads out of the repo, :class:`FileOutOfRangeError <arca.exceptions.FileOutOfRan
 I will be running a lot of tasks from the same repository
 ---------------------------------------------------------
 
-Same as the previous recipe, 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.
+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:
 
 Singe pull
 ++++++++++

docs/index.rst

@@ -18,6 +18,9 @@ Arca's documentation!
 .. image:: https://img.shields.io/github/license/mikicz/arca.svg?style=flat
    :target: https://github.com/mikicz/arca/blob/master/LICENSE
 
+.. image:: https://img.shields.io/readthedocs/arca.svg
+   :target: https://arca.readthedocs.io/
+
 Arca is a library for running Python scripts from git repositories in various states of isolation.
 Arca can also cache the results of these scripts using `dogpile.cache <https://dogpilecache.readthedocs.io/en/latest/>`_.
 

docs/install.rst

@@ -4,6 +4,8 @@ Installation
 Requirements
 ------------
 
+.. remember to update README when updating this
+
 * Python >= 3.6
 
 Requirements for certain backends:
@@ -14,6 +16,8 @@ Requirements for certain backends:
 Installation
 ------------
 
+.. remember to update README when updating this
+
 To install the last stable version:
 
 .. code-block:: bash

docs/quickstart.rst

@@ -4,16 +4,20 @@ Quickstart
 Glossary
 --------
 
-* **Arca** - name of the library. When written as ``Arca``, the main interface class is being referenced.
+.. 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.
 
 Hello World 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.
+.. 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.
 
 Let's imagine we have the following file, called ``hello_world.py``, in a repository ``https://example.com/hello_word.git``,
 on branch ``master``.
@@ -35,9 +39,9 @@ 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
+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, ``arca.exceptions.BuildError`` would be raised.
+If the task failed, :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>`.

docs/settings.rst

@@ -6,7 +6,7 @@ Settings
 Configuring Arca
 ----------------
 
-There are multiple ways to configure ``Arca`` and its backends. (The used options are described :ref:`bellow <options>`.)
+There are multiple ways to configure :class:`Arca <arca.Arca>` and its backends. (The used options are described :ref:`bellow <options>`.)
 
 1. You can initialize the class and backends directly and set it's options via constructor arguments.
 
@@ -35,7 +35,7 @@ For example the same setting as above would be written as:
     "ARCA_BACKEND_CWD": "",  # this one is ignored since it has lower priority
   })
 
-3. You can configure ``Arca`` with environ variables, with keys being the same as in the second method.
+3. You can configure :class:`Arca <arca.Arca>` with environ variables, with keys being the same as in the second method.
 Environ variables override settings from the second method.
 
 You can combine these methods as long as you remember that options explicitly specified in constructors

docs/tasks.rst

@@ -1,7 +1,7 @@
 Tasks
 =====
 
-``Task`` instances are used to define what should be run in the repositories. The definition
+:class:`arca.Task` instances are used to define what should be run in the repositories. The definition
 consists of a string representation of a callable and arguments.
 
 EntryPoints (from the `entrypoints <http://entrypoints.readthedocs.io/en/latest/>`_ library) are used for