More doc updates

README.rst

@@ -25,9 +25,7 @@ As all Python packages, vdirsyncer can be installed with ``pip``::
 
     pip install --user vdirsyncer
 
-Then copy ``example.cfg`` to ``~/.vdirsyncer/config`` and edit it. You can use the
+Then copy ``example.cfg`` to ``~/.vdirsyncer/config`` and edit it.
-`VDIRSYNCER_CONFIG` environment variable to change the path vdirsyncer will
-read the config from.
 
 Run ``vdirsyncer --help`` and check out `the documentation
 <https://vdirsyncer.readthedocs.org/>`_.

docs/api.rst

@@ -2,6 +2,65 @@
 API
 ===
 
+Config Parameters
+=================
+
+.. _general_config:
+
+General Section
+---------------
+
+::
+    [general]
+    status_path = ...
+    #processes = 0
+
+ - ``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``: Optional, 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.
+
+.. _pair_config:
+
+Pair Section
+------------
+
+::
+    [pair pair_name]
+    a = ...
+    b = ...
+    #conflict_resolution = ...
+
+  - ``a`` and ``b`` reference the storages to sync by their names.
+
+  - ``conflict_resolution``: Optional, define how conflicts should be handled.
+    A conflict occurs when one item changed on both sides since the last sync.
+    Valid values are ``a wins`` and ``b wins``. By default, vdirsyncer will
+    show an error and abort the synchronization.
+
+.. _storage_config:
+
+Storage Section
+---------------
+
+::
+    [storage storage_name]
+    type = ...
+
+  - ``type`` defines which kind of storage is defined. See :ref:`storages`.
+
+  - Any further parameters are passed on to the storage class.
+
 .. _storages:
 
 Supported Storages

docs/tutorial.rst

@@ -23,35 +23,21 @@ By default, *vdirsyncer* looks for its configuration file at
 ``~/.vdirsyncer/config``. You can use the ``VDIRSYNCER_CONFIG`` environment
 variable to change this path.
 
-::
+The config file should start with a :ref:`general_config <general section>`,
+where the only required parameter is ``status_path``. The following is a
+minimal example::
 
     [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
+A :ref:`pair section <pair_config>` defines two storages ``a`` and ``b`` which
-synchronized. The definition of these storages follows in *storage* sections.
+should be synchronized. The definition of these storages follows in
-This format is copied from OfflineIMAP, where storages are called repositories
+:ref:`storage sections <storage_config>`.  This format is copied from
-and pairs are called accounts.
+OfflineIMAP, where storages are called repositories and pairs are called
+accounts.
 
 The following example synchronizes a single CardDAV-addressbook to
 ``~/.contacts/``::

example.cfg

@@ -5,13 +5,6 @@
 # A folder where vdirsyncer can store some metadata about each pair.
 status_path = ~/.vdirsyncer/status/
 
-# The amount of processes to use when synchronizing. If the CPU of your server
-# is the bottleneck (which is plausible for small homeservers), set this to the
-# number of cores * 2. Defaults to one process for each collection, which means
-# all collections will be synced at once. The value 0 will be ignored, the
-# value 1 disables multiprocessing.
-#processes =
-
 # CARDDAV
 [pair bob_contacts]
 # A `[pair <name>]` block defines two storages `a` and `b` that should be
@@ -66,13 +59,6 @@ url = https://owncloud.example.com/remote.php/carddav/addressbooks/bob/
 # The password can also be fetched from the system password storage or netrc
 #password =
 
-# SSL settings:
-#   `True` - The NSA can spy on you with some effort (use SSL)
-#   `False` - Everybody can spy on you with no effort (don't use SSL)
-#   `path/to/SSL/cert` - People will call you paranoid (if you use a self-
-#                       signed certificate you need to copy it to this machine)
-#verify = True
-
 # CALDAV
 [pair bob_calendar]
 a = bob_calendar_local
@@ -81,7 +67,7 @@ collections = private,work
 
 [storage bob_calendar_local]
 type = filesystem
-path = ~/.config/vdir/calendars/
+path = ~/.calendars/
 fileext = .ics
 
 [storage bob_calendar_remote]
@@ -90,20 +76,3 @@ url = https://owncloud.example.com/remote.php/caldav/calendars/bob/
 #auth = guess
 #username =
 #password =
-#verify = True
-
-# Optional: Specify a time range which should be synchronized. Either both
-# start_date and end_date or neither have to be set. The default is to
-# synchronize everything.  The following example synchronizes from one year in
-# the past to one year in the future.
-
-# All Python expressions are allowed here. The global namespace contains
-# everything from the datetime module. The expression has to evaluate to a
-# datetime.
-#start_date = datetime.now() - timedelta(days=365)
-
-# Here, start_date is also in the namespace.
-#end_date = datetime.now() + timedelta(days=365)
-
-# For more storage types and examples, check out the documentation at
-# https://vdirsyncer.readthedocs.org

vdirsyncer/storage/dav.py

@@ -29,9 +29,11 @@ class DavStorage(Storage):
     :param url: Base URL or an URL to a collection.
     :param username: Username for authentication.
     :param password: Password for authentication.
-    :param verify: Verify SSL certificate, default True.
+    :param verify: Verify SSL certificate, default True. This can also be a
+        local path to a self-signed SSL certificate.
     :param auth: Optional. Either ``basic``, ``digest`` or ``guess``. Default
-        ``guess``.
+        ``guess``. If you know yours, consider setting it explicitly for
+        performance.
     :param useragent: Default ``vdirsyncer``.
     '''
 
@@ -272,6 +274,19 @@ class CaldavStorage(DavStorage):
 
     __doc__ = '''
     CalDAV. Usable as ``caldav`` in the config file.
+
+    You can set a timerange to synchronize with the parameters ``start_date``
+    and ``end_date``. Inside those parameters, you can use any Python
+    expression to return a valid :py:class:`datetime.datetime` object. For
+    example, the following would synchronize the timerange from one year in the
+    past to one year in the future::
+
+        start_date = datetime.now() - timedelta(days=365)
+        end_date = datetime.now() + timedelta(days=365)
+        
+    Either both or none have to be specified. The default is to synchronize
+    everything.
+
     ''' + DavStorage.__doc__ + '''
     :param start_date: Start date of timerange to show, default -inf.
     :param end_date: End date of timerange to show, default +inf.

vdirsyncer/storage/http.py

@@ -51,9 +51,11 @@ class HttpStorage(Storage):
     :param url: URL to the ``.ics`` file.
     :param username: Username for authentication.
     :param password: Password for authentication.
-    :param verify: Verify SSL certificate, default True.
+    :param verify: Verify SSL certificate, default True. This can also be a
+        local path to a self-signed SSL certificate.
     :param auth: Optional. Either ``basic``, ``digest`` or ``guess``. Default
-        ``guess``.
+        ``guess``. If you know yours, consider setting it explicitly for
+        performance.
     :param useragent: Default ``vdirsyncer``.
 
     A simple example::