Add systemd.timer files and a relevant tutorial (#635)

Include a systemd.timer file (the interval can be overridden, as
mentioned in the docs). TBH, I'd suggest downstream packagers of
systemd-based distributions include these files on installation
(activation needs to be done manually anyway).

CHANGELOG.rst

@@ -29,6 +29,9 @@ Version 0.16.0
 - Vdirsyncer now uses more filesystem metadata for determining whether an item
   changed. You will notice a **possibly heavy CPU/IO spike on the first sync
   after upgrading**.
+- **Packagers:** Reference ``systemd.service`` and ``systemd.timer`` unit files
+  are provided. It is recommended to install this if your distribution is
+  systemd-based.
 
 Version 0.15.0
 ==============

contrib/vdirsyncer.service

@@ -0,0 +1,7 @@
+[Unit]
+Description=Synchronize calendars and contacts
+Documentation=https://vdirsyncer.readthedocs.org/
+
+[Service]
+ExecStart=/usr/bin/vdirsyncer sync
+Type=oneshot

contrib/vdirsyncer.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Synchronize vdirs
+
+[Timer]
+OnBootSec=5m
+OnUnitActiveSec=15m
+AccuracySec=5m
+
+[Install]
+WantedBy=timers.target

docs/packaging.rst

@@ -78,3 +78,9 @@ Then change into the ``docs/`` directory and build whatever format you want
 using the ``Makefile`` in there (run ``make`` for the formats you can build).
 
 .. _Sphinx: www.sphinx-doc.org/
+
+Contrib files
+=============
+
+Reference ``systemd.service`` and ``systemd.timer`` unit files are provided. It
+is recommended to install this if your distribution is systemd-based.

docs/tutorials/index.rst

@@ -11,3 +11,4 @@ that other software may only apply to specific versions of them.
     :maxdepth: 1
 
     claws-mail
+    systemd-timer

docs/tutorials/systemd-timer.rst

@@ -0,0 +1,37 @@
+.. _systemd_timer-tutorial:
+
+Running as a systemd.timer
+==========================
+
+vdirsyncer includes unit files to run at an interval (by default every 15±5
+minutes).
+
+.. note::
+
+    These are not installed when installing via pip, only via distribution
+    packages. If you installed via pip, or your distribution doesn't ship systemd
+    unit files, you'll need to download vdirsyncer.service_ and vdirsyncer.timer_
+    into either ``/etc/systemd/user/`` or ``~/.local/share/systemd/user``.
+
+.. _vdirsyncer.service: https://raw.githubusercontent.com/pimutils/vdirsyncer/master/contrib/vdirsyncer.service
+.. _vdirsyncer.timer: https://raw.githubusercontent.com/pimutils/vdirsyncer/master/contrib/vdirsyncer.timer
+
+Activation
+----------
+
+To activate the timer, just run ``systemctl --user enable vdirsyncer.timer``.
+To see logs of previous runs, use ``journalctl --user -u vdirsyncer``.
+
+Configuration
+-------------
+
+It's quite possible that the default "every fifteen minutes" interval isn't to
+your liking. No default will suit everybody, but this is configurable by simply
+running::
+
+    systemctl --user edit vdirsyncer
+
+This will open a blank editor, where you can override the timer by including::
+
+    OnBootSec=5m  # This is how long after boot the first run takes place.
+    OnUnitActiveSec=15m  # This is how often subsequent runs take place.