diff --git a/README.rst b/README.rst index 41bdad2..94b22c5 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ folder or file. The local data can then be accessed via a variety of programs_, none of which have to know or worry about syncing to a server. .. _storages: https://vdirsyncer.pimutils.org/en/latest/config.html#storages -.. _programs: https://vdirsyncer.pimutils.org/en/stable/supported.html +.. _programs: https://vdirsyncer.pimutils.org/en/latest/tutorials/ It aims to be for CalDAV and CardDAV what `OfflineIMAP `_ is for IMAP. diff --git a/docs/contributing.rst b/docs/contributing.rst index 4fab23c..9527cbf 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -58,7 +58,7 @@ Suggesting features If you're suggesting a feature, keep in mind that vdirsyncer tries not to be a full calendar or contacts client, but rather just the piece of software that synchronizes all the data. :doc:`Take a look at the documentation for software -working with vdirsyncer `. +working with vdirsyncer `. Submitting patches, pull requests ================================= diff --git a/docs/index.rst b/docs/index.rst index 740d15a..da8bd04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ vdirsyncer Vdirsyncer synchronizes your calendars and addressbooks between two :ref:`storages `. The most popular purpose is to synchronize a CalDAV/CardDAV server with a local folder or file. The local data can then be -accessed via a variety of :doc:`programs `, none of which have to +accessed via a variety of :doc:`programs `, none of which have to know or worry about syncing to a server. It aims to be for CalDAV and CardDAV what `OfflineIMAP @@ -25,7 +25,6 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP keyring partial-sync config - supported tutorials/index problems diff --git a/docs/supported.rst b/docs/supported.rst deleted file mode 100644 index 8fedd63..0000000 --- a/docs/supported.rst +++ /dev/null @@ -1,280 +0,0 @@ -================== -Supported Software -================== - -Client applications -=================== - -The following software has been reported to work well with vdirsyncer, however, -none of it is regularly tested. - -Calendars ---------- - -- khal_, a CLI calendar application supporting :doc:`vdir `. You can use - :storage:`filesystem` with it. - -- Many graphical calendar apps such as dayplanner_, Orage_ or rainlendar_ save - a calendar in a single ``.ics`` file. You can use :storage:`singlefile` with - those. - -.. _khal: http://lostpackets.de/khal/ -.. _dayplanner: http://www.day-planner.org/ -.. _Orage: http://www.kolumbus.fi/~w408237/orage/ -.. _rainlendar: http://www.rainlendar.net/ - -Task/Todo managers ------------------- - -The iCalendar format also supports saving tasks in form of ``VTODO``-entries, -with the same file extension as normal events: ``.ics``. All CalDAV servers -support synchronizing tasks, vdirsyncer does too. - -- todoman_, a CLI task manager supporting :doc:`vdir `. Its interface is - similar to the ones of Taskwarrior or the todo.txt CLI app. You can use - :storage:`filesystem` with it. - -.. _todoman: https://hugo.barrera.io/journal/2015/03/30/introducing-todoman/ - - -Contacts --------- - -- khard_, a commandline addressbook supporting :doc:`vdir `. You can use - :storage:`filesystem` with it. - -- contactquery.c_, a small program explicitly written for querying vdirs from - mutt. - -- mates_, a commandline addressbook supporting :doc:`vdir `. - -- vdirel_, access :doc:`vdir ` contacts from Emacs. - -- Claws-Mail's addressbook can be fed by a ``.vcf`` file. See :ref:`here - ` for a tutorial. - -.. _khard: https://github.com/scheibler/khard/ -.. _contactquery.c: https://github.com/t-8ch/snippets/blob/master/contactquery.c -.. _mates: https://github.com/pimutils/mates.rs -.. _vdirel: https://github.com/DamienCassou/vdirel - -.. _supported-servers: - -Supported servers -================= - -CalDAV and CardDAV servers not listed here may work anyway. - -Radicale --------- - -Radicale_ is a very lightweight server, however, it intentionally doesn't -implement the CalDAV and CardDAV standards completely, which might lead to -issues even with very well-written clients. Apart from its non-conformity with -standards, there are multiple other problems with its code quality and the way -it is maintained. Consider using e.g. Xandikos_ instead. - -That said, vdirsyncer is continuously tested against the git version and the -latest PyPI release of Radicale. - -- Vdirsyncer can't create collections on Radicale. -- Radicale doesn't `support time ranges in the calendar-query of CalDAV - `_, so setting ``start_date`` - and ``end_date`` for :storage:`caldav` will have no or unpredicted - consequences. - -- `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all - items of a collection `_. - - You have to set ``item_types = ["VTODO", "VEVENT"]`` in - :storage:`caldav` for vdirsyncer to work with those versions. - -.. _Radicale: http://radicale.org/ - - -.. _owncloud_setup: - -ownCloud --------- - -Vdirsyncer is continuously tested against the latest version of ownCloud_:: - - [storage cal] - type = "caldav" - url = "https://example.com/remote.php/dav/" - username = ... - password = ... - - [storage card] - type = "carddav" - url = "https://example.com/remote.php/dav/" - username = ... - password = ... - -- *Versions older than 7.0.0:* ownCloud uses SabreDAV, which had problems - detecting collisions and race-conditions. The problems were reported and are - fixed in SabreDAV's repo, and the corresponding fix is also in ownCloud since - 7.0.0. See :gh:`16` for more information. - -.. _ownCloud: https://owncloud.org/ - -nextCloud ---------- - -Vdirsyncer is continuously tested against the latest version of nextCloud_:: - - [storage cal] - type = "caldav" - url = "https://nextcloud.example.com/" - username = ... - password = ... - - [storage card] - type = "carddav" - url = "https://nextcloud.example.com/" - -- WebCAL-subscriptions can't be discovered by vdirsyncer. See `this relevant - issue `_. - -.. _nextCloud: https://nextcloud.com/ - - -FastMail --------- - -Vdirsyncer is irregularly tested against FastMail_. There are no known issues -with it. `FastMail's support pages -`_ provide -the settings to use:: - - [storage cal] - type = "caldav" - url = "https://caldav.messagingengine.com/" - username = ... - password = ... - - [storage card] - type = "carddav" - url = "https://carddav.messagingengine.com/" - username = ... - password = ... - -.. _FastMail: https://www.fastmail.com/ - -.. _icloud_setup: - -iCloud ------- - -Vdirsyncer is regularly tested against iCloud_. - -:: - - [storage cal] - type = "caldav" - url = "https://caldav.icloud.com/" - username = ... - password = ... - - [storage card] - type = "carddav" - url = "https://contacts.icloud.com/" - username = ... - password = ... - -Problems: - -- Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem to be a - way to do two-factor auth over the DAV APIs) You'll need to use `app-specific - passwords `_ instead. -- iCloud has a few special requirements when creating collections. In principle - vdirsyncer can do it, but it is recommended to create them from an Apple - client (or the iCloud web interface). - - - iCloud requires a minimum length of collection names. - - Calendars created by vdirsyncer cannot be used as tasklists. - -.. _iCloud: https://www.icloud.com/ - -.. _davmail_setup: - -DavMail (Exchange, Outlook) ---------------------------- - -DavMail_ is a proxy program that allows you to use Card- and CalDAV clients -with Outlook. That allows you to use vdirsyncer with Outlook. - -In practice your success with DavMail may wildly vary. Depending on your -Exchange server you might get confronted with weird errors of all sorts -(including data-loss). - -**Make absolutely sure you use the latest DavMail**:: - - [storage outlook] - type = "caldav" - url = "http://localhost:1080/users/user@example.com/calendar/" - username = "user@example.com" - password = ... - -- Older versions of DavMail handle URLs case-insensitively. See :gh:`144`. -- DavMail is handling malformed data on the Exchange server very poorly. In - such cases the `Calendar Checking Tool for Outlook - `_ might - help. -- In some cases, you may see errors about duplicate events. It may look - something like this:: - - error: my_calendar/calendar: Storage "my_calendar_remote/calendar" contains multiple items with the same UID or even content. Vdirsyncer will now abort the synchronization of this collection, because the fix for this is not clear; It could be the result of a badly behaving server. You can try running: - error: - error: vdirsyncer repair my_calendar_remote/calendar - error: - error: But make sure to have a backup of your data in some form. The offending hrefs are: - [...] - - In order to fix this, you can try the Remove-DuplicateAppointments.ps1_ - PowerShell script that Microsoft has come up with in order to remove duplicates. - -.. _DavMail: http://davmail.sourceforge.net/ -.. _Remove-DuplicateAppointments.ps1: https://blogs.msdn.microsoft.com/emeamsgdev/2015/02/12/powershell-remove-duplicate-calendar-appointments/ - -Baikal ------- - -Vdirsyncer is continuously tested against the latest version of Baikal_. - -- Baikal up to ``0.2.7`` also uses an old version of SabreDAV, with the same - issue as ownCloud, see :gh:`160`. This issue is fixed in later versions. - -.. _Baikal: http://baikal-server.com/ - -Google ------- - -Using vdirsyncer with Google Calendar is possible as of 0.10, but it is not -tested frequently. You can use :storage:`google_contacts` and -:storage:`google_calendar`. - -For more information see :gh:`202` and :gh:`8`. - -Xandikos --------- - -Xandikos_ is a lightweight, yet complete CalDAV and CardDAV server, backed by -git. Vdirsyncer is continuously tested against its latest version. - -After running ``./bin/xandikos --defaults -d $HOME/dav``, you should be able to -point vdirsyncer against the root of Xandikos like this:: - - [storage cal] - type = "caldav" - url = "https://xandikos.example.com/" - username = ... - password = ... - - [storage card] - type = "carddav" - url = "https://xandikos.example.com/" - username = ... - password = ... - -.. _Xandikos: https://github.com/jelmer/xandikos diff --git a/docs/tutorial.rst b/docs/tutorial.rst index eeb16a9..28f5132 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -90,7 +90,7 @@ However, if new collections are created on the server, it will not automatically start synchronizing those [2]_. You need to run ``vdirsyncer discover`` again to re-fetch this list instead. -.. [1] You'll want to :doc:`use a helper program for this `. +.. [1] You'll want to :doc:`use a helper program for this `. .. [2] Because collections are added rarely, and checking for this case before every synchronization isn't worth the overhead. diff --git a/docs/tutorials/baikal.rst b/docs/tutorials/baikal.rst new file mode 100644 index 0000000..815750d --- /dev/null +++ b/docs/tutorials/baikal.rst @@ -0,0 +1,10 @@ +====== +Baikal +====== + +Vdirsyncer is continuously tested against the latest version of Baikal_. + +- Baikal up to ``0.2.7`` also uses an old version of SabreDAV, with the same + issue as ownCloud, see :gh:`160`. This issue is fixed in later versions. + +.. _Baikal: http://baikal-server.com/ diff --git a/docs/tutorials/davmail.rst b/docs/tutorials/davmail.rst new file mode 100644 index 0000000..61fc401 --- /dev/null +++ b/docs/tutorials/davmail.rst @@ -0,0 +1,41 @@ +.. _davmail_setup: + +=========================== +DavMail (Exchange, Outlook) +=========================== + +DavMail_ is a proxy program that allows you to use Card- and CalDAV clients +with Outlook. That allows you to use vdirsyncer with Outlook. + +In practice your success with DavMail may wildly vary. Depending on your +Exchange server you might get confronted with weird errors of all sorts +(including data-loss). + +**Make absolutely sure you use the latest DavMail**:: + + [storage outlook] + type = "caldav" + url = "http://localhost:1080/users/user@example.com/calendar/" + username = "user@example.com" + password = ... + +- Older versions of DavMail handle URLs case-insensitively. See :gh:`144`. +- DavMail is handling malformed data on the Exchange server very poorly. In + such cases the `Calendar Checking Tool for Outlook + `_ might + help. +- In some cases, you may see errors about duplicate events. It may look + something like this:: + + error: my_calendar/calendar: Storage "my_calendar_remote/calendar" contains multiple items with the same UID or even content. Vdirsyncer will now abort the synchronization of this collection, because the fix for this is not clear; It could be the result of a badly behaving server. You can try running: + error: + error: vdirsyncer repair my_calendar_remote/calendar + error: + error: But make sure to have a backup of your data in some form. The offending hrefs are: + [...] + + In order to fix this, you can try the Remove-DuplicateAppointments.ps1_ + PowerShell script that Microsoft has come up with in order to remove duplicates. + +.. _DavMail: http://davmail.sourceforge.net/ +.. _Remove-DuplicateAppointments.ps1: https://blogs.msdn.microsoft.com/emeamsgdev/2015/02/12/powershell-remove-duplicate-calendar-appointments/ diff --git a/docs/tutorials/fastmail.rst b/docs/tutorials/fastmail.rst new file mode 100644 index 0000000..7c53a1f --- /dev/null +++ b/docs/tutorials/fastmail.rst @@ -0,0 +1,22 @@ +======== +FastMail +======== + +Vdirsyncer is irregularly tested against FastMail_. There are no known issues +with it. `FastMail's support pages +`_ provide +the settings to use:: + + [storage cal] + type = "caldav" + url = "https://caldav.messagingengine.com/" + username = ... + password = ... + + [storage card] + type = "carddav" + url = "https://carddav.messagingengine.com/" + username = ... + password = ... + +.. _FastMail: https://www.fastmail.com/ diff --git a/docs/tutorials/google.rst b/docs/tutorials/google.rst new file mode 100644 index 0000000..36340af --- /dev/null +++ b/docs/tutorials/google.rst @@ -0,0 +1,9 @@ +====== +Google +====== + +Using vdirsyncer with Google Calendar is possible as of 0.10, but it is not +tested frequently. You can use :storage:`google_contacts` and +:storage:`google_calendar`. + +For more information see :gh:`202` and :gh:`8`. diff --git a/docs/tutorials/icloud.rst b/docs/tutorials/icloud.rst new file mode 100644 index 0000000..c79b59f --- /dev/null +++ b/docs/tutorials/icloud.rst @@ -0,0 +1,35 @@ +.. _icloud_setup: + +====== +iCloud +====== + +Vdirsyncer is regularly tested against iCloud_. + +:: + + [storage cal] + type = "caldav" + url = "https://caldav.icloud.com/" + username = ... + password = ... + + [storage card] + type = "carddav" + url = "https://contacts.icloud.com/" + username = ... + password = ... + +Problems: + +- Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem to be a + way to do two-factor auth over the DAV APIs) You'll need to use `app-specific + passwords `_ instead. +- iCloud has a few special requirements when creating collections. In principle + vdirsyncer can do it, but it is recommended to create them from an Apple + client (or the iCloud web interface). + + - iCloud requires a minimum length of collection names. + - Calendars created by vdirsyncer cannot be used as tasklists. + +.. _iCloud: https://www.icloud.com/ diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst index 7a086e0..5fa59d2 100644 --- a/docs/tutorials/index.rst +++ b/docs/tutorials/index.rst @@ -5,10 +5,59 @@ Other tutorials The following section contains tutorials not explicitly about any particular core function of vdirsyncer. They usually show how to integrate vdirsyncer with third-party software. Because of that, it may be that the information regarding -that other software may only apply to specific versions of them. +that other software only applies to specific versions of them. + +.. note:: + Please :doc:`contribute ` your own tutorials too! Pages are + often only stubs and are lacking full examples. + +Ćlient applications +=================== .. toctree:: :maxdepth: 1 claws-mail systemd-timer + todoman + +Further applications, with missing pages: + +- khal_, a CLI calendar application supporting :doc:`vdir `. You can use + :storage:`filesystem` with it. +- Many graphical calendar apps such as dayplanner_, Orage_ or rainlendar_ save + a calendar in a single ``.ics`` file. You can use :storage:`singlefile` with + those. +- khard_, a commandline addressbook supporting :doc:`vdir `. You can use + :storage:`filesystem` with it. +- contactquery.c_, a small program explicitly written for querying vdirs from + mutt. +- mates_, a commandline addressbook supporting :doc:`vdir `. +- vdirel_, access :doc:`vdir ` contacts from Emacs. + +.. _khal: http://lostpackets.de/khal/ +.. _dayplanner: http://www.day-planner.org/ +.. _Orage: http://www.kolumbus.fi/~w408237/orage/ +.. _rainlendar: http://www.rainlendar.net/ +.. _khard: https://github.com/scheibler/khard/ +.. _contactquery.c: https://github.com/t-8ch/snippets/blob/master/contactquery.c +.. _mates: https://github.com/pimutils/mates.rs +.. _vdirel: https://github.com/DamienCassou/vdirel + +.. _supported-servers: + +Servers +======= + +.. toctree:: + :maxdepth: 1 + + baikal + davmail + fastmail + google + icloud + nextcloud + owncloud + radicale + xandikos diff --git a/docs/tutorials/nextcloud.rst b/docs/tutorials/nextcloud.rst new file mode 100644 index 0000000..3e8fcc9 --- /dev/null +++ b/docs/tutorials/nextcloud.rst @@ -0,0 +1,20 @@ +========= +nextCloud +========= + +Vdirsyncer is continuously tested against the latest version of nextCloud_:: + + [storage cal] + type = "caldav" + url = "https://nextcloud.example.com/" + username = ... + password = ... + + [storage card] + type = "carddav" + url = "https://nextcloud.example.com/" + +- WebCAL-subscriptions can't be discovered by vdirsyncer. See `this relevant + issue `_. + +.. _nextCloud: https://nextcloud.com/ diff --git a/docs/tutorials/owncloud.rst b/docs/tutorials/owncloud.rst new file mode 100644 index 0000000..3121d05 --- /dev/null +++ b/docs/tutorials/owncloud.rst @@ -0,0 +1,26 @@ +.. _owncloud_setup: + +======== +ownCloud +======== + +Vdirsyncer is continuously tested against the latest version of ownCloud_:: + + [storage cal] + type = "caldav" + url = "https://example.com/remote.php/dav/" + username = ... + password = ... + + [storage card] + type = "carddav" + url = "https://example.com/remote.php/dav/" + username = ... + password = ... + +- *Versions older than 7.0.0:* ownCloud uses SabreDAV, which had problems + detecting collisions and race-conditions. The problems were reported and are + fixed in SabreDAV's repo, and the corresponding fix is also in ownCloud since + 7.0.0. See :gh:`16` for more information. + +.. _ownCloud: https://owncloud.org/ diff --git a/docs/tutorials/radicale.rst b/docs/tutorials/radicale.rst new file mode 100644 index 0000000..6a9998a --- /dev/null +++ b/docs/tutorials/radicale.rst @@ -0,0 +1,26 @@ +======== +Radicale +======== + +Radicale_ is a very lightweight server, however, it intentionally doesn't +implement the CalDAV and CardDAV standards completely, which might lead to +issues even with very well-written clients. Apart from its non-conformity with +standards, there are multiple other problems with its code quality and the way +it is maintained. Consider using e.g. :doc:`xandikos` instead. + +That said, vdirsyncer is continuously tested against the git version and the +latest PyPI release of Radicale. + +- Vdirsyncer can't create collections on Radicale. +- Radicale doesn't `support time ranges in the calendar-query of CalDAV + `_, so setting ``start_date`` + and ``end_date`` for :storage:`caldav` will have no or unpredicted + consequences. + +- `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all + items of a collection `_. + + You have to set ``item_types = ["VTODO", "VEVENT"]`` in + :storage:`caldav` for vdirsyncer to work with those versions. + +.. _Radicale: http://radicale.org/ diff --git a/docs/tutorials/todoman.rst b/docs/tutorials/todoman.rst new file mode 100644 index 0000000..b7e1f2e --- /dev/null +++ b/docs/tutorials/todoman.rst @@ -0,0 +1,13 @@ +======= +Todoman +======= + +The iCalendar format also supports saving tasks in form of ``VTODO``-entries, +with the same file extension as normal events: ``.ics``. Many CalDAV servers +support synchronizing tasks, vdirsyncer does too. + +todoman_ is a CLI task manager supporting :doc:`vdir `. Its interface is +similar to the ones of Taskwarrior or the todo.txt CLI app. You can use +:storage:`filesystem` with it. + +.. _todoman: https://hugo.barrera.io/journal/2015/03/30/introducing-todoman/ diff --git a/docs/tutorials/xandikos.rst b/docs/tutorials/xandikos.rst new file mode 100644 index 0000000..d698760 --- /dev/null +++ b/docs/tutorials/xandikos.rst @@ -0,0 +1,23 @@ +======== +Xandikos +======== + +Xandikos_ is a lightweight, yet complete CalDAV and CardDAV server, backed by +git. Vdirsyncer is continuously tested against its latest version. + +After running ``./bin/xandikos --defaults -d $HOME/dav``, you should be able to +point vdirsyncer against the root of Xandikos like this:: + + [storage cal] + type = "caldav" + url = "https://xandikos.example.com/" + username = ... + password = ... + + [storage card] + type = "carddav" + url = "https://xandikos.example.com/" + username = ... + password = ... + +.. _Xandikos: https://github.com/jelmer/xandikos