Add tutorial

docs/index.rst

@@ -30,6 +30,7 @@ Table of Contents
 .. toctree::
    :maxdepth: 1
 
+   tutorial
    storages
    keyring
    server_support

docs/tutorial.rst

@@ -0,0 +1,117 @@
+========
+Tutorial
+========
+
+Installation
+============
+
+ - Make sure you have Python 2.7+ or Python 3.3+ installed.
+
+ - ``pip install --user vdirsyncer``.
+
+ - Check if the ``vdirsyncer`` command is available.
+
+Configuration
+=============
+
+.. note::
+    The `example.cfg from the repository
+    <https://github.com/untitaker/vdirsyncer/blob/master/example.cfg>`_
+    contains a very terse version of this.
+
+By default, *vdirsyncer* looks for its configuration file at
+``~/.vdirsyncer/config``. You can use the ``VDIRSYNCER_CONFIG`` environment
+variable to change this path.
+
+::
+    [general]
+    status_path = ~/.vdirsyncer/status/
+
+The config file should start with the *general section*, where the only required
+parameter is ``status_path``.The supported parameters are:
+
+ - ``status_path``: A directory where vdirsyncer will store metadata for the
+   next sync. The data is needed to determine whether a new item means it has
+   been added on one side or deleted on the other.
+
+ - ``processes`` defines the amount of maximal connections to use for syncing.
+   By default there is no limit, which means vdirsyncer will try to open a
+   connection for each collection to be synced. The value ``0`` is ignored.
+   Setting this to ``1`` will only synchronize one collection at a time.
+   
+   While this often greatly increases performance, you might have valid reasons
+   to set this to a smaller number. For example, your DAV server running on a
+   Raspberry Pi is so slow that multiple connections don't help much, since the
+   CPU and not the network is the bottleneck.
+
+After the general section, an arbitrary amount of *pair and storage sections*
+might come.
+
+A *pair* section defines two storages ``a`` and ``b`` which should be
+synchronized. The definition of these storages follows in *storage* sections.
+This format is copied from OfflineIMAP, where storages are called repositories
+and pairs are called accounts.
+
+The following example synchronizes a single CardDAV-addressbook to
+``~/.contacts/``::
+
+    [pair my_contacts]
+    a = my_contacts_local
+    b = my_contacts_remote
+
+    [storage my_contacts_local]
+    type = filesystem
+    path = ~/.contacts/
+    fileext = .vcf
+
+    [storage my_contacts_remote]
+    type = carddav
+    url = https://owncloud.example.com/remote.php/carddav/addressbooks/bob/default/
+    username = bob
+    password = asdf
+
+After running ``vdirsyncer sync``, ``~/.contacts/`` will contain a bunch of
+``.vcf`` files which all contain a contact in ``VCARD`` format each. You can
+modify their content, add new ones and delete some, and your changes will be
+synchronized to the CalDAV server after you run ``vdirsyncer sync`` again. For
+further reference, it uses the storages
+:py:class:`vdirsyncer.storage.FilesystemStorage` and
+:py:class:`vdirsyncer.storage.CarddavStorage`.
+
+But what if we want to synchronize multiple addressbooks from the same server?
+Of course we could create new pairs and storages for each addressbook, but that
+is very tedious to do. Instead we will use a shortcut:
+
+  - Remove the last segment from the URL, so that it ends with ``.../bob/``
+    instead of ``.../bob/default/``.
+
+  - Add the following line to the *pair* section::
+    
+        [pair my_contacts]
+        ...
+        collections = default,work
+
+This will synchronize
+``https://owncloud.example.com/remote.php/carddav/addressbooks/bob/default/``
+with ``~/.contacts/default/`` and
+``https://owncloud.example.com/remote.php/carddav/addressbooks/bob/work/`` with
+``~/.contacts/work/``. Under the hood, vdirsyncer also just copies the pairs
+and storages for each collection and appends the collection name to the path or
+URL.
+
+It almost seems like it could work. But what if the same item is changed on
+both sides? What should vdirsyncer do? By default, it will show an ugly error
+message, which is surely a way to avoid the problem. Another way to solve that
+ambiguity is to add another line to the *pair* section::
+
+    [pair my_contacts]
+    ...
+    conflict_resolution = b wins
+
+Earlier we wrote that ``b = my_contacts_remote``, so when vdirsyncer encounters
+the situation where an item changed on both sides, it will simply overwrite the
+local item with the one from the server. Of course ``a wins`` is also a valid
+value.
+
+Calendar sync works almost the same. Just swap ``type = carddav`` for ``type =
+caldav`` and ``fileext = .vcf`` for ``fileext = .ics``.