From 88ba70a460a4550bae9aa216809138454b9b7832 Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Mon, 22 Apr 2013 23:15:44 +0200
Subject: [PATCH] docs: mopidy-convert-config usage

---
 docs/changelog.rst |  9 +++++----
 docs/running.rst   | 50 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 6a4ab026..9245b2a8 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -23,11 +23,12 @@ and improved.
   Python file. This makes configuration easier for users, and also makes it
   possible for Mopidy extensions to have their own config sections.
 
-- Many config values got slightly modified names. We've made a configuration
-  conversion tool to convert the old ``settings.py`` to a new ``mopidy.conf``
-  file. This tool takes care of all the renamed config values as well.
+  Many config values got slightly modified names.
 
-  TODO: Describe how to use the configuration conversion tool.
+  We've made a tool named :option:`mopidy-convert-config` for automatically
+  converting the old ``settings.py`` to a new ``mopidy.conf`` file. This tool
+  takes care of all the renamed config values as well. See
+  :ref:`mopidy-convert-config` for details on how to use it.
 
 - A long wanted feature: You can now enable or disable specific frontends or
   backends without having to redefine :attr:`~mopidy.settings.FRONTENDS` or
diff --git a/docs/running.rst b/docs/running.rst
index 7e0bacbb..d5280990 100644
--- a/docs/running.rst
+++ b/docs/running.rst
@@ -89,3 +89,53 @@ mopidy-scan command
 .. cmdoption:: -v, --verbose
 
     Show more output: debug level and higher.
+
+
+.. _mopidy-convert-config:
+
+mopidy-convert-config command
+=============================
+
+.. program:: mopidy-convert-config
+
+This program does not take any options. It looks for the pre-0.14 settings file
+at ``$XDG_CONFIG_DIR/mopidy/settings.py``, and if it exists it converts it and
+ouputs a Mopidy 0.14 compatible ini-format configuration. If you don't already
+have a config file at ``$XDG_CONFIG_DIR/mopidy/mopidy.conf``, you're asked if
+you want to save the converted config to that file.
+
+Example usage::
+
+    $ cat ~/.config/mopidy/settings.py
+    LOCAL_MUSIC_PATH = u'~/music'
+    MPD_SERVER_HOSTNAME = u'::'
+    SPOTIFY_PASSWORD = u'secret'
+    SPOTIFY_USERNAME = u'alice'
+
+    $ mopidy-convert-config
+    Checking /home/alice/.config/mopidy/settings.py
+    Converted config:
+
+    [spotify]
+    username = alice
+    password = ********
+
+    [mpd]
+    hostname = ::
+
+    [local]
+    media_dir = ~/music
+
+    Write new config to /home/alice/.config/mopidy/mopidy.conf? [yN] y
+    Done.
+
+    $ cat ~/.config/mopidy/mopidy.conf
+    [spotify]
+    username = alice
+    password = secret
+
+    [mpd]
+    hostname = ::
+
+    [local]
+    media_dir = ~/music