Add docs for partial-sync

CHANGELOG.rst

@@ -14,7 +14,8 @@ Version 0.14.0
 
 - ``vdirsyncer sync`` now continues other uploads if one upload failed.  The
   exit code in such situations is still non-zero.
-- Add ``partial_sync`` option to pair section.
+- Add ``partial_sync`` option to pair section. See :ref:`the config docs
+  <partial_sync_def>`.
 
 Version 0.13.1
 ==============

docs/config.rst

@@ -101,13 +101,18 @@ Pair Section
 
   Vdirsyncer never attempts to "automatically merge" the two items.
 
+.. _partial_sync_def:
+
 - ``partial_sync``: Assume A is read-only, B not. If you change items on B,
   vdirsyncer can't sync the changes to A. What should happen instead?
 
   - ``error``: An error is shown.
-  - ``ignore``: The change is ignored.
+  - ``ignore``: The change is ignored. However: Events deleted in B still
+    reappear if they're updated in A.
   - ``revert`` (default): The change is reverted on next sync.
 
+  See also :ref:`partial_sync_tutorial`.
+
 - ``metadata``: Metadata keys that should be synchronized when ``vdirsyncer
   metasync`` is executed. Example::
 

docs/index.rst

@@ -23,6 +23,7 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP
    tutorial
    ssl-tutorial
    keyring
+   partial-sync
    config
    supported
    problems

docs/partial-sync.rst

@@ -0,0 +1,72 @@
+.. _partial_sync_tutorial:
+
+===============================
+Syncing with read-only storages
+===============================
+
+If you want to subscribe to a public, read-only `WebCAL
+<https://en.wikipedia.org/wiki/Webcal>`_-calendar but neither your server nor
+your calendar apps support that (or support it insufficiently), vdirsyncer can
+be used to synchronize such a public calendar ``A`` with a new calendar ``B``
+of your own and keep ``B`` updated.
+
+Step 1: Create the target calendar
+==================================
+
+First you need to create the calendar you want to sync the WebCAL-calendar
+with. Most servers offer a web interface for this. You then need to note the
+CalDAV URL of your calendar. Note that this URL should directly point to the
+calendar you just created, which means you would have one such URL for each
+calendar you have.
+
+Step 2: Creating the config
+===========================
+
+Paste this into your vdirsyncer config::
+
+    [pair holidays]
+    a = holidays_public
+    b = holidays_private
+    collections = null
+
+    [storage holidays_public]
+    type = http
+    # The URL to your iCalendar file.
+    url = ...
+
+    [storage holidays_private]
+    type = caldav
+    # The direct URL to your calendar.
+    url = ...
+    # The credentials to your CalDAV server
+    username = ...
+    password = ...
+
+Then run ``vdirsyncer discover holidays`` and ``vdirsyncer sync holidays``, and
+your previously created calendar should be filled with events.
+
+Step 3: The partial_sync parameter
+==================================
+
+.. versionadded:: 0.14
+
+You may get into a situation where you want to hide or modify some events from
+your ``holidays`` calendar. If you try to do that at this point, you'll notice
+that vdirsyncer will revert any changes you've made after a few times of
+running ``sync``. This is because vdirsyncer wants to keep everything in sync,
+and it can't synchronize changes to the public holidays-calendar because it
+doesn't have the rights to do so.
+
+For such purposes you can set the ``partial_sync`` parameter to ``ignore``::
+
+    [pair holidays]
+    a = holidays_public
+    b = holidays_private
+    collections = null
+    partial_sync = ignore
+
+See :ref:`the config docs <partial_sync_def>` for more information.
+
+.. _nextCloud: https://nextcloud.com/
+.. _Baikal: http://sabre.io/baikal/
+.. _DAViCal: http://www.davical.org/