docs: Update config page howtos

docs/config.rst

@@ -1,32 +1,38 @@
-********
+*************
-Settings
+Configuration
-********
+*************
 
-Mopidy has lots of settings. Luckily, you only need to change a few, and stay
+Mopidy has quite a few config values to tweak. Luckily, you only need to change
-ignorant of the rest. Below you can find guides for typical configuration
+a few, and stay ignorant of the rest. Below you can find guides for typical
-changes you may want to do, and a complete listing of available settings.
+configuration changes you may want to do, and a listing of the available config
+values.
 
 
-Changing settings
+Changing configuration
-=================
+======================
 
-Mopidy reads settings from the file ``~/.config/mopidy/settings.py``, where
+Mopidy primarily reads config from the file ``~/.config/mopidy/mopidy.conf``,
-``~`` means your *home directory*. If your username is ``alice`` and you are
+where ``~`` means your *home directory*. If your username is ``alice`` and you
-running Linux, the settings file should probably be at
+are running Linux, the settings file should probably be at
-``/home/alice/.config/mopidy/settings.py``.
+``/home/alice/.config/mopidy/mopidy.conf``.
 
-You can either create the settings file yourself, or run the ``mopidy``
+You can either create the configuration file yourself, or run the ``mopidy``
 command, and it will create an empty settings file for you.
 
-When you have created the settings file, open it in a text editor, and add
+When you have created the configuration file, open it in a text editor, and add
 settings you want to change. If you want to keep the default value for a
 setting, you should *not* redefine it in your own settings file.
 
-A complete ``~/.config/mopidy/settings.py`` may look as simple as this::
+A complete ``~/.config/mopidy/mopidy.conf`` may look as simple as this:
 
-    MPD_SERVER_HOSTNAME = u'::'
+.. code-block:: ini
-    SPOTIFY_USERNAME = u'alice'
+
-    SPOTIFY_PASSWORD = u'mysecret'
+    [mpd]
+    hostname = ::
+
+    [spotify]
+    username = alice
+    password = mysecret
 
 
 .. _music-from-spotify:
@@ -35,10 +41,16 @@ Music from Spotify
 ==================
 
 If you are using the Spotify backend, which is the default, enter your Spotify
-Premium account's username and password into the file, like this::
+Premium account's username and password into the file, like this:
 
-    SPOTIFY_USERNAME = u'myusername'
+.. code-block:: ini
-    SPOTIFY_PASSWORD = u'mysecret'
+
+    [spotify]
+    username = myusername
+    password = mysecret
+
+This will only work if you have the Spotify Premium subscription. Spotify
+Unlimited will not work.
 
 
 .. _music-from-local-storage:
@@ -48,9 +60,8 @@ Music from local storage
 
 If you want use Mopidy to play music you have locally at your machine instead
 of or in addition to using Spotify, you need to review and maybe change some of
-the ``LOCAL_*`` settings. See :mod:`mopidy.settings`, for a full list of
+the local backend config values. See :ref:`local-backend`, for a complete list.
-available settings. Then you need to generate a tag cache for your local
+Then you need to generate a tag cache for your local music...
-music...
 
 
 .. _generating-a-tag-cache:
@@ -58,28 +69,26 @@ music...
 Generating a tag cache
 ----------------------
 
-Before Mopidy 0.3 the local storage backend relied purely on ``tag_cache``
+The program :command:`mopidy-scan` will scan the path set in the
-files generated by the original MPD server. To remedy this the command
+:confval:`local/media_dir` config value for any media files and build a MPD
-:command:`mopidy-scan` was created. The program will scan your current
+compatible ``tag_cache``.
-:attr:`mopidy.settings.LOCAL_MUSIC_PATH` and build a MPD compatible
-``tag_cache``.
 
 To make a ``tag_cache`` of your local music available for Mopidy:
 
-#. Ensure that :attr:`mopidy.settings.LOCAL_MUSIC_PATH` points to where your
+#. Ensure that the :confval:`local/media_dir` config value points to where your
    music is located. Check the current setting by running::
 
-    mopidy --list-settings
+    mopidy --show-config
 
-#. Scan your music library. The command outputs the ``tag_cache`` to
+#. Scan your media library. The command outputs the ``tag_cache`` to
-   ``stdout``, which means that you will need to redirect the output to a file
+   standard output, which means that you will need to redirect the output to a
-   yourself::
+   file yourself::
 
     mopidy-scan > tag_cache
 
 #. Move the ``tag_cache`` file to the location
-   :attr:`mopidy.settings.LOCAL_TAG_CACHE_FILE` is set to, or change the
+   set in the :confval:`local/tag_cache_file` config value, or change the
-   setting to point to where your ``tag_cache`` file is.
+   config value to point to where your ``tag_cache`` file is.
 
 #. Start Mopidy, find the music library in a client, and play some local music!
 
@@ -91,14 +100,14 @@ 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 :attr:`mopidy.settings.MPD_SERVER_HOSTNAME`.
+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
+MPD password authentication by setting the :confval:`mpd/password` config value
-:attr:`mopidy.settings.MPD_SERVER_PASSWORD` to the password you want to use.
+to the password you want to use.  If the password is set, Mopidy will require
-If the password is set, Mopidy will require MPD clients to provide the password
+MPD clients to provide the password before they can do anything else. Mopidy
-before they can do anything else. Mopidy only supports a single password, and
+only supports a single password, and do not support different permission
-do not support different permission schemes like the original MPD server.
+schemes like the original MPD server.
 
 
 Scrobbling tracks to Last.fm
@@ -107,10 +116,13 @@ Scrobbling tracks to Last.fm
 If you want to submit the tracks you are playing to your `Last.fm
 <http://www.last.fm/>`_ profile, make sure you've installed the dependencies
 found at :mod:`mopidy.frontends.scrobbler` and add the following to your
-settings file::
+settings file:
 
-    LASTFM_USERNAME = u'myusername'
+.. code-block:: ini
-    LASTFM_PASSWORD = u'mysecret'
+
+    [scrobbler]
+    username = myusername
+    password = mysecret
 
 
 .. _install-desktop-file:
@@ -137,7 +149,7 @@ in the Ubuntu Sound Menu, and may be restarted by selecting it there.
 The Ubuntu Sound Menu interacts with Mopidy's MPRIS frontend,
 :mod:`mopidy.frontends.mpris`. The MPRIS frontend supports the minimum
 requirements of the `MPRIS specification <http://www.mpris.org/>`_. The
-``TrackList`` and the ``Playlists`` interfaces of the spec are not supported.
+``TrackList`` interface of the spec is not supported.
 
 
 Using a custom audio sink
@@ -161,13 +173,16 @@ sound from Mopidy either, as Mopidy by default uses GStreamer's
 against Mopidy.
 
 If you for some reason want to use some other GStreamer audio sink than
-``autoaudiosink``, you can set the setting :attr:`mopidy.settings.OUTPUT` to a
+``autoaudiosink``, you can set the :confval:`audio/output` config value to a
 partial GStreamer pipeline description describing the GStreamer sink you want
 to use.
 
-Example of ``settings.py`` for using OSS4::
+Example ``mopidy.conf`` for using OSS4:
 
-    OUTPUT = u'oss4sink'
+.. code-block:: ini
+
+    [audio]
+    output = oss4sink
 
 Again, this is the equivalent of the following ``gst-inspect`` command, so make
 this work first::
@@ -186,33 +201,37 @@ server simultaneously. To use the SHOUTcast output, do the following:
 #. Install, configure and start the Icecast server. It can be found in the
    ``icecast2`` package in Debian/Ubuntu.
 
-#. Set :attr:`mopidy.settings.OUTPUT` to ``lame ! shout2send``. An Ogg Vorbis
+#. Set the :confval:`audio/output` config value to ``lame ! shout2send``. An
-   encoder could be used instead of the lame MP3 encoder.
+   Ogg Vorbis encoder could be used instead of the lame MP3 encoder.
 
 #. You might also need to change the ``shout2send`` default settings, run
    ``gst-inspect-0.10 shout2send`` to see the available settings. Most likely
    you want to change ``ip``, ``username``, ``password``, and ``mount``. For
    example, to set the username and password, use:
-   ``lame ! shout2send username="foobar" password="s3cret"``.
+
+   .. code-block:: ini
+
+       [audio]
+       output = lame ! shout2send username="alice" password="secret"
 
 Other advanced setups are also possible for outputs. Basically, anything you
 can use with the ``gst-launch-0.10`` command can be plugged into
-:attr:`mopidy.settings.OUTPUT`.
+:confval:`audio/output`.
 
 
-Custom settings
+Custom configuration values
-===============
+===========================
 
-Mopidy's settings validator will stop you from defining any settings in your
+Mopidy's settings validator will stop you from defining any config values in
-settings file that Mopidy doesn't know about. This may sound obnoxious, but it
+your settings file that Mopidy doesn't know about. This may sound obnoxious,
-helps you detect typos in your settings, and deprecated settings that should be
+but it helps us detect typos in your settings, and deprecated settings that
-removed or updated.
+should be removed or updated.
 
-If you're extending Mopidy in some way, and want to use Mopidy's settings
+If you're extending Mopidy, and want to use Mopidy's configuration
-system, you can prefix your settings with ``CUSTOM_`` to get around the
+system, you can add new sections to the config without triggering the config
-settings validator. We recommend that you choose names like
+validator. We recommend that you choose a good and unique name for the config
-``CUSTOM_MYAPP_MYSETTING`` so that multiple custom extensions to Mopidy can be
+section so that multiple extensions to Mopidy can be used at the same time
-used at the same time without any danger of naming collisions.
+without any danger of naming collisions.
 
 
 Available settings

docs/index.rst

@@ -42,7 +42,7 @@ User documentation
 
     installation/index
     installation/raspberrypi
-    settings
+    config
     running
     clients/index
     authors

docs/installation/index.rst

@@ -42,7 +42,7 @@ in the same way as you get updates to the rest of your distribution.
        sudo apt-get update
        sudo apt-get install mopidy
 
-#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
+#. Finally, you need to set a couple of :doc:`config values </config>`, and then
    you're ready to :doc:`run Mopidy </running>`.
 
 When a new release of Mopidy is out, and you can't wait for you system to
@@ -89,8 +89,8 @@ package found in AUR.
    install `python2-pylast
    <https://aur.archlinux.org/packages/python2-pylast/>`_ from AUR.
 
-#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
+#. Finally, you need to set a couple of :doc:`config values </config>`, and
-   you're ready to :doc:`run Mopidy </running>`.
+   then you're ready to :doc:`run Mopidy </running>`.
 
 
 OS X: Install from Homebrew and Pip
@@ -140,8 +140,8 @@ Pip.
 
        sudo pip install -U pyspotify pylast mopidy
 
-#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
+#. Finally, you need to set a couple of :doc:`config values </config>`, and
-   you're ready to :doc:`run Mopidy </running>`.
+   then you're ready to :doc:`run Mopidy </running>`.
 
 
 Otherwise: Install from source using Pip
@@ -264,5 +264,5 @@ can install Mopidy from PyPI using Pip.
 
         sudo pip install mopidy==dev
 
-#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
+#. Finally, you need to set a couple of :doc:`config values </config>`, and
-   you're ready to :doc:`run Mopidy </running>`.
+   then you're ready to :doc:`run Mopidy </running>`.