docs: Fix lots of broken module documentation

docs/api/audio.rst

@@ -4,6 +4,10 @@
 Audio API
 *********
 
+.. module:: mopidy.audio
+    :synopsis: Thin wrapper around the parts of GStreamer we use
+
+
 The audio API is the interface we have built around GStreamer to support our
 specific use cases. Most backends should be able to get by with simply setting
 the URI of the resource they want to play, for these cases the default playback

docs/api/backends.rst

@@ -4,6 +4,9 @@
 Backend API
 ***********
 
+.. module:: mopidy.backends.base
+    :synopsis: The API implemented by backends
+
 The backend API is the interface that must be implemented when you create a
 backend. If you are working on a frontend and need to access the backend, see
 the :ref:`core-api`.

docs/api/core.rst

@@ -4,6 +4,9 @@
 Core API
 ********
 
+.. module:: mopidy.core
+    :synopsis: Core API for use by frontends
+
 
 The core API is the interface that is used by frontends like
 :mod:`mopidy.frontends.mpd`. The core layer is inbetween the frontends and the

docs/modules/audio/mixers/auto.rst

@@ -0,0 +1,6 @@
+*********************************************
+:mod:`mopidy.audio.mixers.auto` -- Auto mixer
+*********************************************
+
+.. automodule:: mopidy.audio.mixers.auto
+    :synopsis: Mixer element which automatically selects the real mixer to use

docs/modules/audio/mixers/fake.rst

@@ -0,0 +1,6 @@
+*********************************************
+:mod:`mopidy.audio.mixers.fake` -- Fake mixer
+*********************************************
+
+.. automodule:: mopidy.audio.mixers.fake
+    :synopsis: Fake mixer for use in tests

docs/modules/audio/mixers/nad.rst

@@ -0,0 +1,6 @@
+*********************************************
+:mod:`mopidy.audio.mixers.nad` -- NAD mixer
+*********************************************
+
+.. automodule:: mopidy.audio.mixers.nad
+    :synopsis: Mixer element for controlling volume on NAD amplifiers

docs/modules/backends/local.rst

@@ -4,4 +4,3 @@
 
 .. automodule:: mopidy.backends.local
     :synopsis: Backend for playing music files on local storage
-    :members:

docs/modules/backends/spotify.rst

@@ -4,4 +4,3 @@
 
 .. automodule:: mopidy.backends.spotify
     :synopsis: Backend for the Spotify music streaming service
-    :members:

docs/modules/frontends/lastfm.rst

@@ -4,4 +4,3 @@
 
 .. automodule:: mopidy.frontends.lastfm
     :synopsis: Last.fm scrobbler frontend
-    :members:

docs/modules/frontends/mpd.rst

@@ -4,7 +4,6 @@
 
 .. automodule:: mopidy.frontends.mpd
     :synopsis: MPD server frontend
-    :members:
 
 
 MPD dispatcher
@@ -27,6 +26,7 @@ Audio output
 ------------
 
 .. automodule:: mopidy.frontends.mpd.protocol.audio_output
+    :synopsis: MPD protocol: audio output
     :members:
 
 
@@ -34,6 +34,7 @@ Command list
 ------------
 
 .. automodule:: mopidy.frontends.mpd.protocol.command_list
+    :synopsis: MPD protocol: command list
     :members:
 
 
@@ -41,6 +42,7 @@ Connection
 ----------
 
 .. automodule:: mopidy.frontends.mpd.protocol.connection
+    :synopsis: MPD protocol: connection
     :members:
 
 
@@ -48,12 +50,15 @@ Current playlist
 ----------------
 
 .. automodule:: mopidy.frontends.mpd.protocol.current_playlist
+    :synopsis: MPD protocol: current playlist
     :members:
 
+
 Music database
 --------------
 
 .. automodule:: mopidy.frontends.mpd.protocol.music_db
+    :synopsis: MPD protocol: music database
     :members:
 
 
@@ -61,6 +66,7 @@ Playback
 --------
 
 .. automodule:: mopidy.frontends.mpd.protocol.playback
+    :synopsis: MPD protocol: playback
     :members:
 
 
@@ -68,6 +74,7 @@ Reflection
 ----------
 
 .. automodule:: mopidy.frontends.mpd.protocol.reflection
+    :synopsis: MPD protocol: reflection
     :members:
 
 
@@ -75,6 +82,7 @@ Status
 ------
 
 .. automodule:: mopidy.frontends.mpd.protocol.status
+    :synopsis: MPD protocol: status
     :members:
 
 
@@ -82,6 +90,7 @@ Stickers
 --------
 
 .. automodule:: mopidy.frontends.mpd.protocol.stickers
+    :synopsis: MPD protocol: stickers
     :members:
 
 
@@ -89,4 +98,5 @@ Stored playlists
 ----------------
 
 .. automodule:: mopidy.frontends.mpd.protocol.stored_playlists
+    :synopsis: MPD protocol: stored playlists
     :members:

docs/modules/frontends/mpris.rst

@@ -4,4 +4,3 @@
 
 .. automodule:: mopidy.frontends.mpris
     :synopsis: MPRIS frontend
-    :members:

docs/settings.rst

@@ -29,6 +29,8 @@ A complete ``~/.config/mopidy/settings.py`` may look as simple as this::
     SPOTIFY_PASSWORD = u'mysecret'
 
 
+.. _music-from-spotify:
+
 Music from Spotify
 ==================
 
@@ -39,6 +41,8 @@ Premium account's username and password into the file, like this::
     SPOTIFY_PASSWORD = u'mysecret'
 
 
+.. _music-from-local-storage:
+
 Music from local storage
 ========================
 

mopidy/audio/actor.py

@@ -231,7 +231,7 @@ class Audio(pykka.ThreadingActor):
         Set position in milliseconds.
 
         :param position: the position in milliseconds
-        :type volume: int
+        :type position: int
         :rtype: :class:`True` if successful, else :class:`False`
         """
         self._playbin.get_state()  # block until state changes are done

mopidy/audio/mixers/auto.py

@@ -1,3 +1,17 @@
+"""Mixer element that automatically selects the real mixer to use.
+
+This is Mopidy's default mixer.
+
+**Dependencies:**
+
+- None
+
+**Settings:**
+
+- If this wasn't the default, you would set :attr:`mopidy.settings.MIXER`
+  to ``autoaudiomixer`` to use this mixer.
+"""
+
 import pygst
 pygst.require('0.10')
 import gst

mopidy/audio/mixers/fake.py

@@ -1,3 +1,14 @@
+"""Fake mixer for use in tests.
+
+**Dependencies:**
+
+- None
+
+**Settings:**
+
+- Set :attr:`mopidy.settings.MIXER` to ``fakemixer`` to use this mixer.
+"""
+
 import pygst
 pygst.require('0.10')
 import gobject

mopidy/audio/mixers/nad.py

@@ -1,3 +1,50 @@
+"""Mixer that controls volume using a NAD amplifier.
+
+**Dependencies:**
+
+- pyserial (python-serial in Debian/Ubuntu)
+
+- The NAD amplifier must be connected to the machine running Mopidy using a
+  serial cable.
+
+**Settings:**
+
+- Set :attr:`mopidy.settings.MIXER` to ``nadmixer`` to use it. You probably
+  also needs to add some properties to the ``MIXER`` setting.
+
+Supported properties includes:
+
+``port``:
+    The serial device to use, defaults to ``/dev/ttyUSB0``. This must be
+    set correctly for the mixer to work.
+
+``source``:
+    The source that should be selected on the amplifier, like ``aux``,
+    ``disc``, ``tape``, ``tuner``, etc. Leave unset if you don't want the
+    mixer to change it for you.
+
+``speakers-a``:
+    Set to ``on`` or ``off`` if you want the mixer to make sure that
+    speaker set A is turned on or off. Leave unset if you don't want the
+    mixer to change it for you.
+
+``speakers-b``:
+    See ``speakers-a``.
+
+Configuration examples::
+
+    # Minimum configuration, if the amplifier is available at /dev/ttyUSB0
+    MIXER = u'nadmixer'
+
+    # Minimum configuration, if the amplifier is available elsewhere
+    MIXER = u'nadmixer port=/dev/ttyUSB3'
+
+    # Full configuration
+    MIXER = (
+        u'nadmixer port=/dev/ttyUSB0 '
+        u'source=aux speakers-a=on speakers-b=off')
+"""
+
 import logging
 
 import pygst
@@ -76,7 +123,7 @@ class NadMixer(gst.Element, gst.ImplementsInterface, gst.interfaces.Mixer):
 
 class NadTalker(pykka.ThreadingActor):
     """
-    Independent thread which does the communication with the NAD amplifier
+    Independent thread which does the communication with the NAD amplifier.
 
     Since the communication is done in an independent thread, Mopidy won't
     block other requests while doing rather time consuming work like

mopidy/backends/dummy.py

@@ -1,3 +1,19 @@
+"""A dummy backend for use in tests.
+
+This backend implements the backend API in the simplest way possible.  It is
+used in tests of the frontends.
+
+The backend handles URIs starting with ``dummy:``.
+
+**Dependencies:**
+
+- None
+
+**Settings:**
+
+- None
+"""
+
 import pykka
 
 from mopidy.backends import base
@@ -5,13 +21,6 @@ from mopidy.models import Playlist
 
 
 class DummyBackend(pykka.ThreadingActor, base.Backend):
-    """
-    A backend which implements the backend API in the simplest way possible.
-    Used in tests of the frontends.
-
-    Handles URIs starting with ``dummy:``.
-    """
-
     def __init__(self, audio):
         super(DummyBackend, self).__init__()
 

mopidy/backends/local/__init__.py

@@ -1,2 +1,24 @@
+"""A backend for playing music from a local music archive.
+
+This backend handles URIs starting with ``file:``.
+
+See :ref:`music-from-local-storage` for further instructions on using this
+backend.
+
+**Issues:**
+
+https://github.com/mopidy/mopidy/issues?labels=Local+backend
+
+**Dependencies:**
+
+- None
+
+**Settings:**
+
+- :attr:`mopidy.settings.LOCAL_MUSIC_PATH`
+- :attr:`mopidy.settings.LOCAL_PLAYLIST_PATH`
+- :attr:`mopidy.settings.LOCAL_TAG_CACHE_FILE`
+"""
+
 # flake8: noqa
 from .actor import LocalBackend

mopidy/backends/local/actor.py

@@ -11,20 +11,6 @@ logger = logging.getLogger(u'mopidy.backends.local')
 
 
 class LocalBackend(pykka.ThreadingActor, base.Backend):
-    """
-    A backend for playing music from a local music archive.
-
-    **Dependencies:**
-
-    - None
-
-    **Settings:**
-
-    - :attr:`mopidy.settings.LOCAL_MUSIC_PATH`
-    - :attr:`mopidy.settings.LOCAL_PLAYLIST_PATH`
-    - :attr:`mopidy.settings.LOCAL_TAG_CACHE_FILE`
-    """
-
     def __init__(self, audio):
         super(LocalBackend, self).__init__()
 

mopidy/backends/spotify/__init__.py

@@ -1,2 +1,34 @@
+"""A backend for playing music from Spotify
+
+`Spotify <http://www.spotify.com/>`_ is a music streaming service. The backend
+uses the official `libspotify
+<http://developer.spotify.com/en/libspotify/overview/>`_ library and the
+`pyspotify <http://github.com/mopidy/pyspotify/>`_ Python bindings for
+libspotify. This backend handles URIs starting with ``spotify:``.
+
+See :ref:`music-from-spotify` for further instructions on using this backend.
+
+.. note::
+
+    This product uses SPOTIFY(R) CORE but is not endorsed, certified or
+    otherwise approved in any way by Spotify. Spotify is the registered
+    trade mark of the Spotify Group.
+
+**Issues:**
+
+https://github.com/mopidy/mopidy/issues?labels=Spotify+backend
+
+**Dependencies:**
+
+- libspotify >= 11, < 12 (libspotify11 package from apt.mopidy.com)
+- pyspotify >= 1.7, < 1.8 (python-spotify package from apt.mopidy.com)
+
+**Settings:**
+
+- :attr:`mopidy.settings.SPOTIFY_CACHE_PATH`
+- :attr:`mopidy.settings.SPOTIFY_USERNAME`
+- :attr:`mopidy.settings.SPOTIFY_PASSWORD`
+"""
+
 # flake8: noqa
 from .actor import SpotifyBackend

mopidy/backends/spotify/actor.py

@@ -9,34 +9,6 @@ logger = logging.getLogger('mopidy.backends.spotify')
 
 
 class SpotifyBackend(pykka.ThreadingActor, base.Backend):
-    """
-    A backend for playing music from the `Spotify <http://www.spotify.com/>`_
-    music streaming service. The backend uses the official `libspotify
-    <http://developer.spotify.com/en/libspotify/overview/>`_ library and the
-    `pyspotify <http://github.com/winjer/pyspotify/>`_ Python bindings for
-    libspotify.
-
-    .. note::
-
-        This product uses SPOTIFY(R) CORE but is not endorsed, certified or
-        otherwise approved in any way by Spotify. Spotify is the registered
-        trade mark of the Spotify Group.
-
-    **Issues:**
-    https://github.com/mopidy/mopidy/issues?labels=backend-spotify
-
-    **Dependencies:**
-
-    - libspotify >= 10, < 11 (libspotify10 package from apt.mopidy.com)
-    - pyspotify >= 1.5 (python-spotify package from apt.mopidy.com)
-
-    **Settings:**
-
-    - :attr:`mopidy.settings.SPOTIFY_CACHE_PATH`
-    - :attr:`mopidy.settings.SPOTIFY_USERNAME`
-    - :attr:`mopidy.settings.SPOTIFY_PASSWORD`
-    """
-
     # Imports inside methods are to prevent loading of __init__.py to fail on
     # missing spotify dependencies.
 

mopidy/frontends/lastfm.py

@@ -1,3 +1,27 @@
+"""
+Frontend which scrobbles the music you play to your `Last.fm
+<http://www.last.fm>`_ profile.
+
+.. note::
+
+    This frontend requires a free user account at Last.fm.
+
+**Dependencies:**
+
+- `pylast <http://code.google.com/p/pylast/>`_ >= 0.5.7
+
+**Settings:**
+
+- :attr:`mopidy.settings.LASTFM_USERNAME`
+- :attr:`mopidy.settings.LASTFM_PASSWORD`
+
+**Usage:**
+
+Make sure :attr:`mopidy.settings.FRONTENDS` includes
+``mopidy.frontends.lastfm.LastfmFrontend``. By default, the setting includes
+the Last.fm frontend.
+"""
+
 import logging
 import time
 
@@ -18,24 +42,6 @@ API_SECRET = '94d9a09c0cd5be955c4afaeaffcaefcd'
 
 
 class LastfmFrontend(pykka.ThreadingActor, CoreListener):
-    """
-    Frontend which scrobbles the music you play to your `Last.fm
-    <http://www.last.fm>`_ profile.
-
-    .. note::
-
-        This frontend requires a free user account at Last.fm.
-
-    **Dependencies:**
-
-    - `pylast <http://code.google.com/p/pylast/>`_ >= 0.5.7
-
-    **Settings:**
-
-    - :attr:`mopidy.settings.LASTFM_USERNAME`
-    - :attr:`mopidy.settings.LASTFM_PASSWORD`
-    """
-
     def __init__(self, core):
         super(LastfmFrontend, self).__init__()
         self.lastfm = None

mopidy/frontends/mpd/__init__.py

@@ -1,2 +1,25 @@
+"""The MPD server frontend.
+
+MPD stands for Music Player Daemon. MPD is an independent project and server.
+Mopidy implements the MPD protocol, and is thus compatible with clients for the
+original MPD server.
+
+**Dependencies:**
+
+- None
+
+**Settings:**
+
+- :attr:`mopidy.settings.MPD_SERVER_HOSTNAME`
+- :attr:`mopidy.settings.MPD_SERVER_PORT`
+- :attr:`mopidy.settings.MPD_SERVER_PASSWORD`
+
+**Usage:**
+
+Make sure :attr:`mopidy.settings.FRONTENDS` includes
+``mopidy.frontends.mpd.MpdFrontend``. By default, the setting includes the MPD
+frontend.
+"""
+
 # flake8: noqa
 from .actor import MpdFrontend

mopidy/frontends/mpd/actor.py

@@ -12,20 +12,6 @@ logger = logging.getLogger('mopidy.frontends.mpd')
 
 
 class MpdFrontend(pykka.ThreadingActor, CoreListener):
-    """
-    The MPD frontend.
-
-    **Dependencies:**
-
-    - None
-
-    **Settings:**
-
-    - :attr:`mopidy.settings.MPD_SERVER_HOSTNAME`
-    - :attr:`mopidy.settings.MPD_SERVER_PORT`
-    - :attr:`mopidy.settings.MPD_SERVER_PASSWORD`
-    """
-
     def __init__(self, core):
         super(MpdFrontend, self).__init__()
         hostname = network.format_hostname(settings.MPD_SERVER_HOSTNAME)

mopidy/frontends/mpris/__init__.py

@@ -1,2 +1,54 @@
+"""
+Frontend which lets you control Mopidy through the Media Player Remote
+Interfacing Specification (`MPRIS <http://www.mpris.org/>`_) D-Bus
+interface.
+
+An example of an MPRIS client is the `Ubuntu Sound Menu
+<https://wiki.ubuntu.com/SoundMenu>`_.
+
+**Dependencies:**
+
+- D-Bus Python bindings. The package is named ``python-dbus`` in
+  Ubuntu/Debian.
+
+- ``libindicate`` Python bindings is needed to expose Mopidy in e.g. the
+  Ubuntu Sound Menu. The package is named ``python-indicate`` in
+  Ubuntu/Debian.
+
+- An ``.desktop`` file for Mopidy installed at the path set in
+  :attr:`mopidy.settings.DESKTOP_FILE`. See :ref:`install_desktop_file` for
+  details.
+
+**Settings:**
+
+- :attr:`mopidy.settings.DESKTOP_FILE`
+
+**Usage:**
+
+Make sure :attr:`mopidy.settings.FRONTENDS` includes
+``mopidy.frontends.mpris.MprisFrontend``. By default, the setting includes the
+MPRIS frontend.
+
+**Testing the frontend**
+
+To test, start Mopidy, and then run the following in a Python shell::
+
+    import dbus
+    bus = dbus.SessionBus()
+    player = bus.get_object('org.mpris.MediaPlayer2.mopidy',
+        '/org/mpris/MediaPlayer2')
+
+Now you can control Mopidy through the player object. Examples:
+
+- To get some properties from Mopidy, run::
+
+    props = player.GetAll('org.mpris.MediaPlayer2',
+        dbus_interface='org.freedesktop.DBus.Properties')
+
+- To quit Mopidy through D-Bus, run::
+
+    player.Quit(dbus_interface='org.mpris.MediaPlayer2')
+"""
+
 # flake8: noqa
 from .actor import MprisFrontend

mopidy/frontends/mpris/actor.py

@@ -16,46 +16,6 @@ except ImportError as import_error:
 
 
 class MprisFrontend(pykka.ThreadingActor, CoreListener):
-    """
-    Frontend which lets you control Mopidy through the Media Player Remote
-    Interfacing Specification (`MPRIS <http://www.mpris.org/>`_) D-Bus
-    interface.
-
-    An example of an MPRIS client is the `Ubuntu Sound Menu
-    <https://wiki.ubuntu.com/SoundMenu>`_.
-
-    **Dependencies:**
-
-    - D-Bus Python bindings. The package is named ``python-dbus`` in
-      Ubuntu/Debian.
-    - ``libindicate`` Python bindings is needed to expose Mopidy in e.g. the
-      Ubuntu Sound Menu. The package is named ``python-indicate`` in
-      Ubuntu/Debian.
-    - An ``.desktop`` file for Mopidy installed at the path set in
-      :attr:`mopidy.settings.DESKTOP_FILE`. See :ref:`install_desktop_file` for
-      details.
-
-    **Testing the frontend**
-
-    To test, start Mopidy, and then run the following in a Python shell::
-
-        import dbus
-        bus = dbus.SessionBus()
-        player = bus.get_object('org.mpris.MediaPlayer2.mopidy',
-            '/org/mpris/MediaPlayer2')
-
-    Now you can control Mopidy through the player object. Examples:
-
-    - To get some properties from Mopidy, run::
-
-        props = player.GetAll('org.mpris.MediaPlayer2',
-            dbus_interface='org.freedesktop.DBus.Properties')
-
-    - To quit Mopidy through D-Bus, run::
-
-        player.Quit(dbus_interface='org.mpris.MediaPlayer2')
-    """
-
     def __init__(self, core):
         super(MprisFrontend, self).__init__()
         self.core = core