docs: Improved file/option markup

docs/commands/mopidy-convert-config.rst

@@ -19,8 +19,8 @@ combines results from all music sources, and you can mix tracks from all
 sources in your play queue. Your playlists from Spotify or SoundCloud are also
 available for use.
 
-The ``mopidy-convert-config`` command is used to convert ``settings.py``
+The ``mopidy-convert-config`` command is used to convert :file:`settings.py`
-configuration files used by ``mopidy`` < 0.14 to the ``mopidy.conf`` config
+configuration files used by ``mopidy`` < 0.14 to the :file:`mopidy.conf` config
 file used by ``mopidy`` >= 0.14.
 
 
@@ -30,16 +30,16 @@ Options
 .. 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
+at :file:`{$XDG_CONFIG_DIR}/mopidy/settings.py`, and if it exists it converts
-ouputs a Mopidy 0.14 compatible ini-format configuration. If you don't already
+it and ouputs a Mopidy 0.14 compatible ini-format configuration. If you don't
-have a config file at ``$XDG_CONFIG_DIR/mopidy/mopidy.conf``, you're asked if
+already have a config file at :file:`{$XDG_CONFIG_DIR}/mopidy/mopidy.conf``,
-you want to save the converted config to that file.
+you're asked if you want to save the converted config to that file.
 
 
 Example
 =======
 
-Given the following contents in ``~/.config/mopidy/settings.py``:
+Given the following contents in :file:`~/.config/mopidy/settings.py`:
 
 ::
 
@@ -49,7 +49,7 @@ Given the following contents in ``~/.config/mopidy/settings.py``:
     SPOTIFY_USERNAME = u'alice'
 
 Running ``mopidy-convert-config`` will convert the config and create a new
-``mopidy.conf`` config file:
+:file:`mopidy.conf` config file:
 
 .. code-block:: none
 
@@ -70,7 +70,7 @@ Running ``mopidy-convert-config`` will convert the config and create a new
     Write new config to /home/alice/.config/mopidy/mopidy.conf? [yN] y
     Done.
 
-Contents of ``~/.config/mopidy/mopidy.conf`` after the conversion:
+Contents of :file:`~/.config/mopidy/mopidy.conf` after the conversion:
 
 .. code-block:: ini
 

docs/commands/mopidy.rst

@@ -29,7 +29,7 @@ Options
 
 .. program:: mopidy
 
-.. cmdoption:: -h, --help
+.. cmdoption:: --help, -h
 
     Show help message and exit.
 
@@ -37,11 +37,11 @@ Options
 
     Show Mopidy's version number and exit.
 
-.. cmdoption:: -q, --quiet
+.. cmdoption:: --quiet, -q
 
     Show less output: warning level and higher.
 
-.. cmdoption:: -v, --verbose
+.. cmdoption:: --verbose, -v
 
     Show more output: debug level and higher.
 
@@ -56,7 +56,7 @@ Options
     with a colon. The later files override the earlier ones if there's a
     conflict.
 
-.. cmdoption:: -o <option>, --option <option>
+.. cmdoption:: --option <option>, -o <option>
 
     Specify additional config values in the ``section/key=value`` format. Can
     be provided multiple times.
@@ -79,7 +79,7 @@ Built in commands
 Extension commands
 ==================
 
-Additionally, extensions can provide extra commands. See ``mopidy --help``
+Additionally, extensions can provide extra commands. Run `mopidy --help`
 for a list of what is available on your system and command-specific help.
 Commands for disabled extensions will be listed, but can not be run.
 
@@ -91,10 +91,10 @@ Commands for disabled extensions will be listed, but can not be run.
 Files
 =====
 
-/etc/mopidy/mopidy.conf
+:file:`/etc/mopidy/mopidy.conf`
     System wide Mopidy configuration file.
 
-~/.config/mopidy/mopidy.conf
+:file:`~/.config/mopidy/mopidy.conf`
     Your personal Mopidy configuration file. Overrides any configs from the
     system wide configuration file.
 
@@ -131,6 +131,7 @@ See also
 
 :ref:`mopidy-convert-config(1) <mopidy-convert-config>`
 
+
 Reporting bugs
 ==============
 

docs/config.rst

@@ -3,8 +3,8 @@ Configuration
 *************
 
 Mopidy has a lot of config values you can tweak, but you only need to change a
-few to get up and running. A complete ``~/.config/mopidy/mopidy.conf`` may be
+few to get up and running. A complete :file:`~/.config/mopidy/mopidy.conf` may
-as simple as this:
+be as simple as this:
 
 .. code-block:: ini
 
@@ -15,17 +15,18 @@ as simple as this:
     username = alice
     password = mysecret
 
-Mopidy primarily reads config from the file ``~/.config/mopidy/mopidy.conf``,
+Mopidy primarily reads config from the file
-where ``~`` means your *home directory*. If your username is ``alice`` and you
+:file:`~/.config/mopidy/mopidy.conf`, where ``~`` means your *home directory*.
-are running Linux, the config file should probably be at
+If your username is ``alice`` and you are running Linux, the config file should
-``/home/alice/.config/mopidy/mopidy.conf``. You can either create the
+probably be at :file:`/home/alice/.config/mopidy/mopidy.conf`. You can either
-configuration file yourself, or run the ``mopidy`` command, and it will create
+create the configuration file yourself, or run the ``mopidy`` command, and it
-an empty config file for you and print what config values must be set to
+will create an empty config file for you and print what config values must be
-successfully start Mopidy.
+set to successfully start Mopidy.
 
 When you have created the configuration file, open it in a text editor, and add
 the config values you want to change. If you want to keep the default for a
-config value, you **should not** add it to ``~/.config/mopidy/mopidy.conf``.
+config value, you **should not** add it to
+:file:`~/.config/mopidy/mopidy.conf`.
 
 To see what's the effective configuration for your Mopidy installation, you can
 run :option:`mopidy --show-config`. It will print your full effective config