docs: More prose and less headers in ext docs

docs/config.rst

@@ -1,3 +1,5 @@
+.. _config:
+
 *************
 Configuration
 *************

docs/ext/http.rst

@@ -4,35 +4,77 @@
 Mopidy-HTTP
 ***********
 
-The HTTP extension lets you control Mopidy through HTTP and WebSockets, e.g.
+Mopidy-HTTP is an extension that lets you control Mopidy through HTTP and
-from a web based client. See :ref:`http-api` for details on how to integrate
+WebSockets, for example from a web client. It is bundled with Mopidy and
-with Mopidy over HTTP.
+enabled by default if all dependencies are available.
+
+When it is enabled it starts a web server at the port specified by the
+:confval:`http/port` config value.
+
+.. warning::
+
+    As a simple security measure, the web server is by default only available
+    from localhost. To make it available from other computers, change the
+    :confval:`http/hostname` config value. Before you do so, note that the HTTP
+    extension does not feature any form of user authentication or
+    authorization. Anyone able to access the web server can use the full core
+    API of Mopidy. Thus, you probably only want to make the web server
+    available from your local network or place it behind a web proxy which
+    takes care or user authentication. You have been warned.
+
+
+Using a web based Mopidy client
+===============================
+
+Mopidy-HTTP's web server can also host any static files, for example the HTML,
+CSS, JavaScript, and images needed for a web based Mopidy client. To host
+static files, change the :confval:`http/static_dir` config value to point to
+the root directory of your web client, for example::
+
+    [http]
+    static_dir = /home/alice/dev/the-client
+
+If the directory includes a file named ``index.html``, it will be served on the
+root of Mopidy's web server.
+
+If you're making a web based client and wants to do server side development as
+well, you are of course free to run your own web server and just use Mopidy's
+web server to host the API end points. But, for clients implemented purely in
+JavaScript, letting Mopidy host the files is a simpler solution.
+
+See :ref:`http-api` for details on how to integrate with Mopidy over HTTP. If
+you're looking for a web based client for Mopidy, go check out
+:ref:`http-clients`.
 
 
 Dependencies
 ============
 
+In addition to Mopidy's dependencies, Mopidy-HTTP requires the following:
+
 - cherrypy >= 3.2.2. Available as python-cherrypy3 in Debian/Ubuntu.
 
 - ws4py >= 0.2.3. Available as python-ws4py in newer Debian/Ubuntu and from
-  apt.mopidy.com for older releases of Debian/Ubuntu.
+  `apt.mopidy.com <http://apt.mopidy.com/>`__ for older releases of
+  Debian/Ubuntu.
 
 If you're installing Mopidy with pip, you can run the following command to
 install Mopidy with the extra dependencies for required for Mopidy-HTTP::
 
     pip install --upgrade Mopidy[http]
 
+If you're installing Mopidy from APT, the additional dependencies needed for
+Mopidy-HTTP are always included.
 
-Default configuration
+
-=====================
+Configuration
+=============
+
+See :ref:`config` for general help on configuring Mopidy.
 
 .. literalinclude:: ../../mopidy/http/ext.conf
     :language: ini
 
-
-Configuration values
-====================
-
 .. confval:: http/enabled
 
     If the HTTP extension should be enabled or not.
@@ -67,46 +109,3 @@ Configuration values
     ``$hostname`` and ``$port`` can be used in the name.
 
     Set to an empty string to disable Zeroconf for HTTP.
-
-
-Usage
-=====
-
-The extension is enabled by default if all dependencies are available.
-
-When it is enabled it starts a web server at the port specified by the
-:confval:`http/port` config value.
-
-.. warning:: Security
-
-    As a simple security measure, the web server is by default only available
-    from localhost. To make it available from other computers, change the
-    :confval:`http/hostname` config value. Before you do so, note that the HTTP
-    extension does not feature any form of user authentication or
-    authorization. Anyone able to access the web server can use the full core
-    API of Mopidy. Thus, you probably only want to make the web server
-    available from your local network or place it behind a web proxy which
-    takes care or user authentication. You have been warned.
-
-
-Using a web based Mopidy client
--------------------------------
-
-The web server can also host any static files, for example the HTML, CSS,
-JavaScript, and images needed for a web based Mopidy client. To host static
-files, change the ``http/static_dir`` to point to the root directory of your
-web client, e.g.::
-
-    [http]
-    static_dir = /home/alice/dev/the-client
-
-If the directory includes a file named ``index.html``, it will be served on the
-root of Mopidy's web server.
-
-If you're making a web based client and wants to do server side development as
-well, you are of course free to run your own web server and just use Mopidy's
-web server for the APIs. But, for clients implemented purely in JavaScript,
-letting Mopidy host the files is a simpler solution.
-
-If you're looking for a web based client for Mopidy, go check out
-:ref:`http-clients`.

docs/ext/local.rst

@@ -4,27 +4,61 @@
 Mopidy-Local
 ************
 
-Extension for playing music from a local music archive.
+Mopidy-Local is an extension for playing music from your local music archive.
+It is bundled with Mopidy and enabled by default. Though, you'll have to scan
+your music collection to build a cache of metadata before the Mopidy-Local
+will be able to play your music.
 
 This backend handles URIs starting with ``local:``.
 
 
-Dependencies
+.. _generating-a-local-library:
-============
 
-None. The extension just needs Mopidy.
+Generating a local library
+==========================
+
+The command :command:`mopidy local scan` will scan the path set in the
+:confval:`local/media_dir` config value for any audio files and build a
+library of metadata.
+
+To make a local library for your music available for Mopidy:
+
+#. Ensure that the :confval:`local/media_dir` config value points to where your
+   music is located. Check the current setting by running::
+
+    mopidy config
+
+#. Scan your media library.::
+
+    mopidy local scan
+
+#. Start Mopidy, find the music library in a client, and play some local music!
 
 
-Default configuration
+Pluggable library support
-=====================
+=========================
+
+Local libraries are fully pluggable. What this means is that users may opt to
+disable the current default library ``json``, replacing it with a third
+party one. When running :command:`mopidy local scan` Mopidy will populate
+whatever the current active library is with data. Only one library may be
+active at a time.
+
+To create a new library provider you must create class that implements the
+:class:`mopidy.local.Library` interface and install it in the extension
+registry under ``local:library``. Any data that the library needs to store on
+disc should be stored in :confval:`local/data_dir` using the library name as
+part of the filename or directory to avoid any conflicts.
+
+
+Configuration
+=============
+
+See :ref:`config` for general help on configuring Mopidy.
 
 .. literalinclude:: ../../mopidy/local/ext.conf
     :language: ini
 
-
-Configuration values
-====================
-
 .. confval:: local/enabled
 
     If the local extension should be enabled or not.
@@ -61,51 +95,3 @@ Configuration values
 
     File extensions to exclude when scanning the media directory. Values
     should be separated by either comma or newline.
-
-
-Usage
-=====
-
-If you want use Mopidy to play music you have locally at your machine, you need
-to review and maybe change some of the local extension config values. See above
-for a complete list. Then you need to generate a local library for your local
-music...
-
-
-.. _generating-a-local-library:
-
-Generating a local library
---------------------------
-
-The command :command:`mopidy local scan` will scan the path set in the
-:confval:`local/media_dir` config value for any audio files and build a
-library.
-
-To make a local library for your music available for Mopidy:
-
-#. Ensure that the :confval:`local/media_dir` config value points to where your
-   music is located. Check the current setting by running::
-
-    mopidy config
-
-#. Scan your media library.::
-
-    mopidy local scan
-
-#. Start Mopidy, find the music library in a client, and play some local music!
-
-
-Pluggable library support
--------------------------
-
-Local libraries are fully pluggable. What this means is that users may opt to
-disable the current default library ``json``, replacing it with a third
-party one. When running :command:`mopidy local scan` mopidy will populate
-whatever the current active library is with data. Only one library may be
-active at a time.
-
-To create a new library provider you must create class that implements the
-:class:`mopidy.local.Library` interface and install it in the extension
-registry under ``local:library``. Any data that the library needs to store on
-disc should be stored in :confval:`local/data_dir` using the library name as
-part of the filename or directory to avoid any conflicts.

docs/ext/mpd.rst

@@ -4,8 +4,20 @@
 Mopidy-MPD
 **********
 
-This extension implements an MPD server to make Mopidy available to :ref:`MPD
+Mopidy-MPD is an extension that provides a full MPD server implementation to
-clients <mpd-clients>`.
+make Mopidy available to :ref:`MPD clients <mpd-clients>`. It is bundled with
+Mopidy and enabled by default.
+
+.. warning::
+
+    As a simple security measure, the HTTP server is by default only available
+    from localhost. To make it available from other computers, change the
+    :confval:`mpd/hostname` config value. Before you do so, note that the MPD
+    server does not support any form of encryption and only a single clear
+    text password (see :confval:`mpd/password`) for weak authentication. Anyone
+    able to access the MPD server can control music playback on your computer.
+    Thus, you probably only want to make the MPD server available from your
+    local network. You have been warned.
 
 MPD stands for Music Player Daemon, which is also the name of the `original MPD
 server project <http://mpd.wikia.com/>`_. Mopidy does not depend on the
@@ -21,6 +33,7 @@ Limitations
 This is a non exhaustive list of MPD features that Mopidy doesn't support.
 Items on this list will probably not be supported in the near future.
 
+- Only a single password is supported. It gives all-or-nothing access.
 - Toggling of audio outputs is not supported
 - Channels for client-to-client communication are not supported
 - Stickers are not supported
@@ -38,22 +51,14 @@ near future:
 - Live update of the music database is not supported
 
 
-Dependencies
+Configuration
-============
+=============
 
-None. The extension just needs Mopidy.
+See :ref:`config` for general help on configuring Mopidy.
-
-
-Default configuration
-=====================
 
 .. literalinclude:: ../../mopidy/mpd/ext.conf
     :language: ini
 
-
-Configuration values
-====================
-
 .. confval:: mpd/enabled
 
     If the MPD extension should be enabled or not.
@@ -95,27 +100,3 @@ Configuration values
     ``$hostname`` and ``$port`` can be used in the name.
 
     Set to an empty string to disable Zeroconf for MPD.
-
-
-Usage
-=====
-
-The extension is enabled by default. To connect to the server, use an :ref:`MPD
-client <mpd-clients>`.
-
-
-.. _use-mpd-on-a-network:
-
-Connecting from other machines on the network
----------------------------------------------
-
-As a secure default, Mopidy only accepts connections from ``localhost``. If you
-want to open it for connections from other machines on your network, see
-the documentation for the :confval:`mpd/hostname` config value.
-
-If you open up Mopidy for your local network, you should consider turning on
-MPD password authentication by setting the :confval:`mpd/password` config value
-to the password you want to use.  If the password is set, Mopidy will require
-MPD clients to provide the password before they can do anything else. Mopidy
-only supports a single password, and do not support different permission
-schemes like the original MPD server.

docs/ext/stream.rst

@@ -4,29 +4,32 @@
 Mopidy-Stream
 *************
 
-Extension for playing streaming music.
+Mopidy-Stream is an extension for playing streaming music. It is bundled with
+Mopidy and enabled by default.
 
-The stream backend will handle streaming of URIs matching the
+This backend does not provide a library or playlist storage. It simply accepts
-:confval:`stream/protocols` config value, assuming the needed GStreamer plugins
+any URI added to Mopidy's tracklist that matches any of the protocols in the
-are installed.
+:confval:`stream/protocols` config value. It then tries to retrieve metadata
+and play back the URI using GStreamer. For example, if you're using an MPD
+client, you'll just have to find your clients "add URI" interface, and provide
+it with the URI of a stream.
+
+In addition to playing streams, the extension also understands how to extract
+streams from a lot of playlist formats. This is convenient as most Internet
+radio stations links to playlists instead of directly to the radio streams.
+
+If you're having trouble playing back a stream, run the ``mopidy deps``
+command to check if you have all relevant GStreamer plugins installed.
 
 
-Dependencies
+Configuration
-============
+=============
 
-None. The extension just needs Mopidy.
+See :ref:`config` for general help on configuring Mopidy.
-
-
-Default configuration
-=====================
 
 .. literalinclude:: ../../mopidy/stream/ext.conf
     :language: ini
 
-
-Configuration values
-====================
-
 .. confval:: stream/enabled
 
     If the stream extension should be enabled or not.
@@ -39,17 +42,3 @@ Configuration values
 .. confval:: stream/timeout
 
     Number of milliseconds before giving up looking up stream metadata.
-
-
-Usage
-=====
-
-This backend does not provide a library or similar. It simply takes any URI
-added to Mopidy's tracklist that matches any of the protocols in the
-:confval:`stream/protocols` setting and tries to play back the URI using
-GStreamer. E.g. if you're using an MPD client, you'll just have to find your
-clients "add URI" interface, and provide it with the direct URI of the stream.
-
-Currently the stream backend can only work with URIs pointing direcly at
-streams, and not intermediate playlists which is often used. See :issue:`303`
-to track the development of playlist expansion support.