diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 5051c4b..e0ca40d 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -182,11 +182,10 @@ Version 0.3.3 cause any problems. - Vdirsyncer is now more robust regarding invalid responses from CalDAV servers. This should help with future compatibility with Davmail/Outlook. -- Fix a bug when specifying ``item_types`` of - :py:class:`vdirsyncer.storage.CaldavStorage` in the deprecated config format. +- Fix a bug when specifying ``item_types`` of :storage:`caldav` in the + deprecated config format. - Fix a bug where vdirsyncer would ignore all but one character specified in - ``unsafe_href_chars`` of :py:class:`vdirsyncer.storage.CaldavStorage` and - :py:class:`vdirsyncer.storage.CarddavStorage`. + ``unsafe_href_chars`` of :storage:`caldav` and :storage:`carddav`. Version 0.3.2 ============= @@ -219,11 +218,8 @@ Version 0.3.0 *released on 20 September 2014* -- Add ``verify_fingerprint`` parameter to - :py:class:`vdirsyncer.storage.HttpStorage`, - :py:class:`vdirsyncer.storage.CaldavStorage` and - :py:class:`vdirsyncer.storage.CarddavStorage`, - see :gh:`99` and :ghpr:`106`. +- Add ``verify_fingerprint`` parameter to :storage:`http`, :storage:`caldav` + and :storage:`carddav`, see :gh:`99` and :ghpr:`106`. - Add ``passwordeval`` parameter to :ref:`general_config`, see :gh:`108` and :ghpr:`117`. @@ -303,8 +299,7 @@ Version 0.2.0 instead of the proper etag would have been returned from the upload method. vdirsyncer might do unnecessary copying when upgrading to this version. -- Add the storage :py:class:`vdirsyncer.storage.SingleFileStorage`. See - :gh:`48`. +- Add the storage :storage:`singlefile`. See :gh:`48`. - The ``collections`` parameter for pair sections now accepts the special values ``from a`` and ``from b`` for automatically discovering collections. diff --git a/docs/conf.py b/docs/conf.py index 367cae4..5fc44c5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,11 +91,24 @@ class StorageDocumenter(autodoc.ClassDocumenter): Sphinx' __init__ signature removed.''' objtype = 'storage' - directivetype = 'attribute' + domain = None + directivetype = 'storage' + option_spec = {} + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + from vdirsyncer.storage.base import Storage + return isinstance(member, Storage) def format_signature(self): return '' + def add_directive_header(self, sig): + directive = getattr(self, 'directivetype', self.objtype) + name = self.object.storage_name + self.add_line(u'.. %s:: %s%s' % (directive, name, sig), + '') + def get_doc(self, encoding=None, ignore=1): from vdirsyncer.cli.utils import format_storage_config rv = autodoc.ClassDocumenter.get_doc(self, encoding, ignore) @@ -105,6 +118,9 @@ class StorageDocumenter(autodoc.ClassDocumenter): def setup(app): + from sphinx.domains.python import PyObject + app.add_object_type('storage', 'storage', 'pair: %s; storage', + doc_field_types=PyObject.doc_field_types) app.add_role('gh', github_issue_role) app.add_role('ghpr', github_issue_role) app.add_autodocumenter(StorageDocumenter) diff --git a/docs/problems.rst b/docs/problems.rst index 0491d46..7a828b8 100644 --- a/docs/problems.rst +++ b/docs/problems.rst @@ -19,10 +19,8 @@ Requests-related ImportErrors on Debian-based distributions Debian has had its problems in the past with the Python requests package, see :gh:`82` and :gh:`140`. You have several options for solving this problem: -- Set the ``auth`` parameter of :py:class:`vdirsyncer.storage.CaldavStorage`, - :py:class:`vdirsyncer.storage.CarddavStorage`, and/or - :py:class:`vdirsyncer.storage.HttpStorage` to ``basic`` or ``digest`` (not - ``guess``). +- Set the ``auth`` parameter of :storage:`caldav`, :storage:`carddav`, and/or + :storage:`http` to ``basic`` or ``digest`` (not ``guess``). - Upgrade your installation of the Debian requests package to at least version ``2.4.3-1``. diff --git a/docs/supported.rst b/docs/supported.rst index 8f4ab20..d1033bd 100644 --- a/docs/supported.rst +++ b/docs/supported.rst @@ -12,11 +12,11 @@ Calendars --------- - khal_, a CLI calendar application supporting :doc:`vdir `. You can use - :py:class:`vdirsyncer.storage.FilesystemStorage` with it. + :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 - :py:class:`vdirsyncer.storage.SingleFileStorage` with those. + 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/ @@ -31,7 +31,7 @@ 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 `. You can use - :py:class:`vdirsyncer.storage.FilesystemStorage` with it. + :storage:`filesystem` with it. Its interface is similar to the ones of Taskwarrior or the todo.txt CLI app and should be intuitively usable. @@ -43,7 +43,7 @@ Contacts -------- - khard_, a commandline addressbook supporting :doc:`vdir `. You can use - :py:class:`vdirsyncer.storage.FilesystemStorage` with it. + :storage:`filesystem` with it. - contactquery.c_, a small program explicitly written for querying vdirs from mutt. @@ -76,15 +76,14 @@ 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 :py:class:`vdirsyncer.storage.CaldavStorage` will have - no or unpredicted consequences. + 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 - :py:class:`vdirsyncer.storage.CaldavStorage` for vdirsyncer to work with - those versions. + :storage:`caldav` for vdirsyncer to work with those versions. .. _Radicale: http://radicale.org/ diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 65e3377..9c6c71d 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -89,9 +89,8 @@ 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 [1]_, 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`. +further reference, it uses the storages :storage:`filesystem` and +:storage:`carddav`. .. [1] You'll want to :doc:`use a helper program for this `. diff --git a/docs/vdir.rst b/docs/vdir.rst index 4215662..0aa7d19 100644 --- a/docs/vdir.rst +++ b/docs/vdir.rst @@ -5,8 +5,7 @@ The Vdir Storage Format This document describes a standard for storing calendars and contacts on a filesystem, with the main goal of being easy to implement. -Vdirsyncer synchronizes to vdirs via -:py:class:`vdirsyncer.storage.filesystem.FilesystemStorage`. Each vdir +Vdirsyncer synchronizes to vdirs via :storage:`filesystem`. Each vdir (basically just a directory with some files in it) represents a calendar or addressbook. diff --git a/vdirsyncer/storage/singlefile.py b/vdirsyncer/storage/singlefile.py index 9eb343a..1a2000f 100644 --- a/vdirsyncer/storage/singlefile.py +++ b/vdirsyncer/storage/singlefile.py @@ -37,14 +37,12 @@ class SingleFileStorage(Storage): .. note:: This storage is very slow, and that is unlikely to change. You should - consider using - :py:class:`vdirsyncer.storage.filesystem.FilesystemStorage` if it fits - your usecase. + consider using :storage:`filesystem` if it fits your usecase. :param path: The filepath to the file to be written to. :param encoding: Which encoding the file should use. Defaults to UTF-8. - Example for syncing with :py:class:`vdirsyncer.storage.CaldavStorage`:: + Example for syncing with :storage:`caldav`:: [pair my_calendar] a = my_calendar_local