docs: Add docs for all available mixers

docs/api/mixers.rst

@@ -6,3 +6,62 @@
     :synopsis: Sound mixer interface.
     :members:
     :undoc-members:
+
+
+Internal mixers
+===============
+
+Most users will use on of these internal mixers which controls the volume on
+the computer running Mopidy. If you do not specify which mixer you want to use
+in the settings, Mopidy will choose one for you based upon what OS you run. See
+:attr:`mopidy.settings.default.MIXER` for the defaults.
+
+
+:mod:`mopidy.mixers.alsa` -- ALSA mixer
+---------------------------------------
+
+.. automodule:: mopidy.mixers.alsa
+    :synopsis: ALSA mixer
+    :members:
+
+
+:mod:`mopidy.mixers.dummy` -- Dummy mixer
+-----------------------------------------
+
+.. automodule:: mopidy.mixers.dummy
+    :synopsis: Dummy mixer
+    :members:
+
+
+:mod:`mopidy.mixers.osa` -- Osa mixer
+-------------------------------------
+
+.. automodule:: mopidy.mixers.osa
+    :synopsis: Osa mixer
+    :members:
+
+
+External device mixers
+======================
+
+Mopidy supports controlling volume on external devices instead of on the
+computer running Mopidy through the use of custom mixer implementations. To
+enable one of the following mixers, you must the set `MIXER` setting to point
+to one of the classes found below, and possibly add some extra settings
+required by the mixer you choose.
+
+
+:mod:`mopidy.mixers.denon` -- Denon amplifier mixer
+---------------------------------------------------
+
+.. automodule:: mopidy.mixers.denon
+    :synopsis: Denon amplifier mixer
+    :members:
+
+
+:mod:`mopidy.mixers.nad` -- NAD amplifier mixer
+-----------------------------------------------
+
+.. automodule:: mopidy.mixers.nad
+    :synopsis: NAD amplifier mixer
+    :members:

mopidy/mixers/alsa.py

@@ -3,6 +3,11 @@ import alsaaudio
 from mopidy.mixers import BaseMixer
 
 class AlsaMixer(BaseMixer):
+    """
+    Mixer which uses the Advanced Linux Sound Architecture (ALSA) to control
+    volume.
+    """
+
     def __init__(self):
         self._mixer = alsaaudio.Mixer()
 

mopidy/mixers/denon.py

@@ -8,27 +8,21 @@ from mopidy.settings import MIXER_PORT
 
 logger = logging.getLogger(u'mopidy.mixers.denon')
 
-"""
- Mixer for controlling Denon recivers and amplifiers using the RS-232 protocol.
-
- Connects using the serial specifications from
- Denon's RS-232 Protocol specification.
-
- Communication speed       : 9600bps
- Character length                 : 8 bits
- Parity control                   : None
- Start bit                        : 1 bit
- Stop bit                         : 1 bit
- Communication procedure          : Non procedural
- Communication data length : 135 bytes (maximum)
-
- The external mixer is the authoritative source for the current volume.
- This allows the user to use his remote control the volume without
- mopidy cancelling the volume setting.
-"""
-
 class DenonMixer(BaseMixer):
+    """
+    Mixer for controlling Denon amplifiers and receivers using the RS-232
+    protocol.
+
+    The external mixer is the authoritative source for the current volume.
+    This allows the user to use his remote control the volume without Mopidy
+    cancelling the volume setting.
+    """
+
     def __init__(self):
+        """
+        Connects using the serial specifications from Denon's RS-232 Protocol
+        specification: 9600bps 8N1.
+        """
         self._device = Serial(port=MIXER_PORT, timeout=0.2)
         self._levels = ['99'] + ["%(#)02d" % {'#': v} for v in range(0, 99)]
         self._volume = 0

mopidy/mixers/dummy.py

@@ -1,6 +1,8 @@
 from mopidy.mixers import BaseMixer
 
 class DummyMixer(BaseMixer):
+    """Mixer which just stores and reports the choosen volume."""
+
     def __init__(self):
         self._volume = None
 

mopidy/mixers/nad.py

@@ -9,6 +9,9 @@ logger = logging.getLogger('mopidy.mixers.nad')
 
 class NadMixer(BaseMixer):
     """
+    Mixer for controlling NAD amplifiers and receivers using the NAD RS-232
+    protocol.
+
     The NAD mixer was created using a NAD C 355BEE amplifier, but should also
     work with other NAD amplifiers supporting the same RS-232 protocol (v2.x).
     The C 355BEE does not give you access to the current volume. It only
@@ -18,10 +21,9 @@ class NadMixer(BaseMixer):
 
     Sadly, this means that if you use the remote control to change the volume
     on the amplifier, Mopidy will no longer report the correct volume. To
-    recalibrate the mixer, set the volume to 0, and then back again to the
+    recalibrate the mixer, set the volume to 0 through Mopidy. This will reset
-    level you want. This will reset the amplifier to a known state, including
+    the amplifier to a known state, including powering on the device, selecting
-    powering on the device, selecting the configured speakers and input
+    the configured speakers and input sources.
-    sources.
     """
 
     def __init__(self):

mopidy/mixers/osa.py

@@ -3,16 +3,18 @@ import time
 
 from mopidy.mixers import BaseMixer
 
-CACHE_TTL = 30
-
 class OsaMixer(BaseMixer):
+    """Mixer which uses ``osascript`` on OS X to control volume."""
+
+    CACHE_TTL = 30
+
     _cache = None
     _last_update = None
 
     def _valid_cache(self):
         return (self._cache is not None
             and self._last_update is not None
-            and (int(time.time() - self._last_update) < CACHE_TTL))
+            and (int(time.time() - self._last_update) < self.CACHE_TTL))
 
     def _get_volume(self):
 	if not self._valid_cache():