ext: Doc Registry and setup(), deprecate old methods

mopidy/ext.py

@@ -51,18 +51,54 @@ class Extension(object):
         schema['enabled'] = config_lib.Boolean()
         return schema
 
+    def get_command(self):
+        """Command to expose to command line users running mopidy.
+
+        :returns:
+          Instance of a :class:`~mopidy.commands.Command` class.
+        """
+        pass
+
     def validate_environment(self):
         """Checks if the extension can run in the current environment
 
         For example, this method can be used to check if all dependencies that
-        are needed are installed.
+        are needed are installed. If a problem is found, raise
+        :exc:`~mopidy.exceptions.ExtensionError` with a message explaining the
+        issue.
 
-        :raises: :class:`~mopidy.exceptions.ExtensionError`
+        :raises: :exc:`~mopidy.exceptions.ExtensionError`
         :returns: :class:`None`
         """
         pass
 
     def setup(self, registry):
+        """
+        Register the extension's components in the extension :class:`Registry`.
+
+        For example, to register a backend::
+
+            def setup(self, registry):
+                from .backend import SoundspotBackend
+                registry.add('backend', SoundspotBackend)
+
+        See :meth:`Registry.add` for a list of registry keys with a special
+        meaning. Mopidy will instantiate and start any classes registered
+        under the ``frontend`` and ``backend`` registry keys.
+
+        This method can also be used for other setup tasks not involving the
+        extension registry. For example, to register custom GStreamer
+        elements::
+
+            def setup(self, registry):
+                from .mixer import SoundspotMixer
+                gobject.type_register(SoundspotMixer)
+                gst.element_register(
+                    SoundspotMixer, 'soundspotmixer', gst.RANK_MARGINAL)
+
+        :param registry: the extension registry
+        :type registry: :class:`Registry`
+        """
         for backend_class in self.get_backend_classes():
             registry.add('backend', backend_class)
 
@@ -74,7 +110,8 @@ class Extension(object):
     def get_frontend_classes(self):
         """List of frontend actor classes
 
-        Mopidy will take care of starting the actors.
+        .. deprecated:: 0.18
+            Use :meth:`setup` instead.
 
         :returns: list of :class:`pykka.Actor` subclasses
         """
@@ -83,43 +120,51 @@ class Extension(object):
     def get_backend_classes(self):
         """List of backend actor classes
 
-        Mopidy will take care of starting the actors.
+        .. deprecated:: 0.18
+            Use :meth:`setup` instead.
 
         :returns: list of :class:`~mopidy.backends.base.Backend` subclasses
         """
         return []
 
-    def get_command(self):
-        """Command to expose to command line users running mopidy.
-
-        :returns:
-          Instance of a :class:`~mopidy.commands.Command` class.
-        """
-        pass
-
     def register_gstreamer_elements(self):
-        """Hook for registering custom GStreamer elements
+        """Hook for registering custom GStreamer elements.
 
-        Register custom GStreamer elements by implementing this method.
+        .. deprecated:: 0.18
-        Example::
+            Use :meth:`setup` instead.
-
-            def register_gstreamer_elements(self):
-                from .mixer import SoundspotMixer
-                gobject.type_register(SoundspotMixer)
-                gst.element_register(
-                    SoundspotMixer, 'soundspotmixer', gst.RANK_MARGINAL)
 
         :returns: :class:`None`
         """
         pass
 
 
-# TODO: document
 class Registry(collections.Mapping):
+    """Registry of components provided by Mopidy extensions.
+
+    Passed to the :meth:`~Extension.setup` method of all extensions. The
+    registry can be used like a dict of string keys and lists.
+
+    Some keys have a special meaning, including, but not limited to:
+
+    - ``backend`` is used for Mopidy backend classes.
+    - ``frontend`` is used for Mopidy frontend classes.
+    - ``local:library`` is used for Mopidy-Local libraries.
+
+    Extensions can use the registry for allow other to extend the extension
+    itself. For example the ``Mopidy-Local`` use the ``local:library`` key to
+    allow other extensions to register library providers for ``Mopidy-Local``
+    to use. Extensions should namespace custom keys with the extension's
+    :attr:`~Extension.ext_name`, e.g. ``local:foo`` or ``http:bar``.
+    """
+
     def __init__(self):
         self._registry = {}
 
     def add(self, name, cls):
+        """Add a component to the registry.
+
+        Multiple classes can be registered to the same name.
+        """
         self._registry.setdefault(name, []).append(cls)
 
     def __getitem__(self, name):