Massively improve doc refs

Fix #243

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
+- Fix a bug when specifying ``item_types`` of :storage:`caldav` in the
-  :py:class:`vdirsyncer.storage.CaldavStorage` in the deprecated config format.
+  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
+  ``unsafe_href_chars`` of :storage:`caldav` and :storage:`carddav`.
-  :py:class:`vdirsyncer.storage.CarddavStorage`.
 
 Version 0.3.2
 =============
@@ -219,11 +218,8 @@ Version 0.3.0
 
 *released on 20 September 2014*
 
-- Add ``verify_fingerprint`` parameter to
+- Add ``verify_fingerprint`` parameter to :storage:`http`, :storage:`caldav`
-  :py:class:`vdirsyncer.storage.HttpStorage`,
+  and :storage:`carddav`, see :gh:`99` and :ghpr:`106`.
-  :py:class:`vdirsyncer.storage.CaldavStorage` and
-  :py:class:`vdirsyncer.storage.CarddavStorage`,
-  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
+- Add the storage :storage:`singlefile`. See :gh:`48`.
-  :gh:`48`.
 
 - The ``collections`` parameter for pair sections now accepts the special
   values ``from a`` and ``from b`` for automatically discovering collections.

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),
+                      '<autodoc>')
+
     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)

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`,
+- Set the ``auth`` parameter of :storage:`caldav`, :storage:`carddav`, and/or
-  :py:class:`vdirsyncer.storage.CarddavStorage`, and/or
+  :storage:`http` to ``basic`` or ``digest`` (not ``guess``).
-  :py:class:`vdirsyncer.storage.HttpStorage` to ``basic`` or ``digest`` (not
-  ``guess``).
 
 - Upgrade your installation of the Debian requests package to at least version
   ``2.4.3-1``.

docs/supported.rst

@@ -12,11 +12,11 @@ Calendars
 ---------
 
 - khal_, a CLI calendar application supporting :doc:`vdir <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
+  a calendar in a single ``.ics`` file. You can use :storage:`singlefile` with
-  :py:class:`vdirsyncer.storage.SingleFileStorage` with those.
+  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 <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 <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
   <https://github.com/Kozea/Radicale/issues/146>`_, so setting ``start_date``
-  and ``end_date`` for :py:class:`vdirsyncer.storage.CaldavStorage` will have
+  and ``end_date`` for :storage:`caldav` will have no or unpredicted
-  no or unpredicted consequences.
+  consequences.
 
 - `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all
   items of a collection <https://github.com/Kozea/Radicale/issues/143>`_.
 
   You have to set ``item_types = ["VTODO", "VEVENT"]`` in
-  :py:class:`vdirsyncer.storage.CaldavStorage` for vdirsyncer to work with
+  :storage:`caldav` for vdirsyncer to work with those versions.
-  those versions.
 
 .. _Radicale: http://radicale.org/
 

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
+further reference, it uses the storages :storage:`filesystem` and
-:py:class:`vdirsyncer.storage.FilesystemStorage` and
+:storage:`carddav`.
-:py:class:`vdirsyncer.storage.CarddavStorage`.
 
 .. [1] You'll want to :doc:`use a helper program for this <supported>`.
 

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
+Vdirsyncer synchronizes to vdirs via :storage:`filesystem`. Each vdir
-:py:class:`vdirsyncer.storage.filesystem.FilesystemStorage`. Each vdir
 (basically just a directory with some files in it) represents a calendar or
 addressbook.
 

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
+        consider using :storage:`filesystem` if it fits your usecase.
-        :py:class:`vdirsyncer.storage.filesystem.FilesystemStorage` 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