harmonize all plugins docs

Add a configuration section that lists all options for each plugin.
List options in alphabetic order.
Mention the default value for each option.
Use same sentences to describe concepts common to different plugins eg 'auto
option, install description

docs/plugins/beatport.rst

@@ -18,8 +18,8 @@ both MusicBrainz and (to a lesser degree) Discogs show no matches.
 Installation
 ------------
 
-To see matches from the ``beatport`` plugin, you first have to enable it in
-your configuration (see :doc:`/plugins/index`). Then, install the `requests`_
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`). Then, install the `requests`_
 library (which we need for querying the Beatport API) by typing::
 
     pip install requests

docs/plugins/bpd.rst

@@ -38,13 +38,11 @@ installing GStreamer plugins.
 .. _GStreamer WinBuilds: http://www.gstreamer-winbuild.ylatuya.es/
 .. _Homebrew: http://mxcl.github.com/homebrew/
 
-Using and Configuring
----------------------
-
-BPD is a plugin for beets. It comes with beets, but it's disabled by default.
-To enable it, you'll need to edit your :doc:`configuration file
-</reference/config>` and add ``bpd`` to your ``plugins:`` line.
+Usage
+-----
 
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`).
 Then, you can run BPD by invoking::
 
     $ beet bpd
@@ -69,10 +67,20 @@ the client can just as easily on a different computer from the server as it can
 be run locally. Control your music from your laptop (or phone!) while it plays
 on your headless server box. Rad!
 
-To configure the BPD server, add a ``bpd:`` section to your ``config.yaml``
-file. The configuration values, which are pretty self-explanatory, are ``host``,
-``port``, ``password`` and ``volume``. The volume option sets the initial 
-volume (in percent, default: 100). Here's an example::
+Configuration
+-------------
+
+Available options are pretty self-explanatory :
+
+- ``host``
+  Default: ``u''``
+- ``port``
+  Default: ``6600``
+- ``password``: ``u'``
+- ``volume`` sets the initial volume in percent
+  Default: ``100``
+
+Here's an example::
 
     bpd:
         host: 127.0.0.1
@@ -83,13 +91,13 @@ volume (in percent, default: 100). Here's an example::
 Implementation Notes
 --------------------
 
-In the real MPD, the user can browse a music directory as it appears on disk. In
-beets, we like to abstract away from the directory structure. Therefore, BPD
+In the real MPD, the user can browse a music directory as it appears on disk.
+In beets, we like to abstract away from the directory structure. Therefore, BPD
 creates a "virtual" directory structure (artist/album/track) to present to
-clients. This is static for now and cannot be reconfigured like the real on-disk
-directory structure can. (Note that an obvious solution to this is just string
-matching on items' destination, but this requires examining the entire library
-Python-side for every query.)
+clients. This is static for now and cannot be reconfigured like the real
+on-disk directory structure can. (Note that an obvious solution to this is just
+string matching on items' destination, but this requires examining the entire
+library Python-side for every query.)
 
 We don't currently support versioned playlists. Many clients, however, use
 plchanges instead of playlistinfo to get the current playlist, so plchanges

docs/plugins/bpm.rst

@@ -1,22 +1,29 @@
 BPM Plugin
 ==========
 
-This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by tapping out the beat on your keyboard.
+This ``bpm`` plugin lets you to get the tempo (beats per minute) of a song by
+tapping out the beat on your keyboard.
 
 Usage
 -----
 
-First, enable the plugin ``bpm`` as described in :doc:`/plugins/index`. Then, play a song you want to measure in your favorite media player and type::
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`).
 
-     beet bpm <song> 
+Then, play a song you want to measure in your favorite media player and type::
 
-You'll be prompted to press Enter three times to the rhythm. This typically allows to determine the BPM within 5% accuracy. 
+     beet bpm <song>
 
-The plugin works best if you wrap it in a script that gets the playing song. for instance, with ``mpc`` you can do something like::
+You'll be prompted to press Enter three times to the rhythm. This typically
+allows to determine the BPM within 5% accuracy.
+
+The plugin works best if you wrap it in a script that gets the playing song.
+for instance, with ``mpc`` you can do something like::
 
      beet bpm $(mpc |head -1|tr -d "-")
 
 Credit
 ------
 
-This plugin is inspired by a similar feature present in the Banshee media player.
+This plugin is inspired by a similar feature present in the Banshee media
+player.

docs/plugins/bucket.rst

@@ -7,8 +7,9 @@ The ``bucket`` plugin groups your files into buckets folders representing
 smaller subfolders by grouping albums or artists alphabetically (e.g. *A-F*,
 *G-M*, *N-Z*).
 
-To use the plugin, enable ``bucket`` in your configuration file (see
-:ref:`using-plugins`). The plugin provides a :ref:`template function
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`).
+The plugin provides a :ref:`template function
 <template-functions>` called ``%bucket`` for use in path format expressions::
 
     paths:
@@ -25,25 +26,43 @@ The ``bucket_year`` parameter is used for all substitutions occuring on the
 
 The definition of a range is somewhat loose, and multiple formats are allowed:
 
-- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise) alphanumeric characters in the string you provide. For example, *ABCD*, *A-D*, *A->D*, and *[AD]* are all equivalent.
-- For year ranges: digits characters are extracted and the two extreme years define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are equivalent. If no upper bound is given, the range is extended to current year (unless a later range is defined). For example, *1975* encompasses all years from 1975 until now.
+- For alpha ranges: the range is defined by the lowest and highest (ASCII-wise)
+  alphanumeric characters in the string you provide. For example, *ABCD*,
+  *A-D*, *A->D*, and *[AD]* are all equivalent.
+- For year ranges: digits characters are extracted and the two extreme years
+  define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are
+  equivalent. If no upper bound is given, the range is extended to current year
+  (unless a later range is defined). For example, *1975* encompasses all years
+  from 1975 until now.
 
-If you want to group your files into multiple year ranges, you don't have to
-enumerate them all in `bucket_year` parameter but can activate the ``extrapolate``
-option instead. This option will generate year bucket names by reproducing characteristics
-of declared buckets::
+Configuration
+-------------
 
-    bucket:
-        bucket_year: ['2000-05']
-        extrapolate: true
+Available options :
 
-The above configuration creates five-year ranges for any input year.
+- ``bucket_alpha`` defines ranges to use for all substitutions occuring on
+  textual fields.
+  Default: ``[]``
+- ``bucket_alpha_regex`` allows to define a regex to override a `bucket_alpha`
+  range definition
+  Default: ``{}``
+- ``bucket_year`` defines ranges to use for all substitutions occuring on the
+  `$year` field
+  Default: ``[]``
+- ``extrapolate`` : activate it when you want to group your files into multiple
+  year ranges without enumerating them all. This option will generate year
+  bucket names by reproducing characteristics of declared buckets.
+  Default: ``no``
 
-If the automatic range of an alpha bucket is not sufficient an overriding regular expression can be used::
+Here's an example::
 
       bucket:
+         bucket_year: ['2000-05']
+         extrapolate: true
          bucket_alpha: ['A - D', 'E - L', 'M - R', 'S - Z']
          bucket_alpha_regex:
            'A - D': ^[0-9a-dA-D…äÄ]
 
-The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9 and … (three dots). The other buckets work as ranges (see above).
+The above configuration creates five-year ranges for any input year.
+The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9
+and … (three dots). The other alpha buckets work as ranges.

docs/plugins/chroma.rst

@@ -65,10 +65,10 @@ You will also need a mechanism for decoding audio files supported by the
   need to install anything.
 
 * On Linux, you can install `GStreamer for Python`_, `FFmpeg`_, or `MAD`_ and
-  `pymad`_. How you install these will depend on your distribution. For example,
-  on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch Linux, you want
-  ``pacman -S gstreamer0.10-python``. If you use GStreamer, be sure to install
-  its codec plugins also.
+  `pymad`_. How you install these will depend on your distribution.
+  For example, on Ubuntu, run ``apt-get install python-gst0.10-dev``. On Arch
+  Linux, you want ``pacman -S gstreamer0.10-python``. If you use GStreamer, be
+  sure to install its codec plugins also.
 
 * On Windows, try the Gstreamer "WinBuilds" from the `OSSBuild`_ project.
 
@@ -87,13 +87,12 @@ standard set of Gstreamer plugins. For example, on Ubuntu, install the packages
 ``gstreamer0.10-plugins-good``, ``gstreamer0.10-plugins-bad``, and
 ``gstreamer0.10-plugins-ugly``.
 
-Using
+Usage
 -----
 
-Once you have all the dependencies sorted out, you can enable fingerprinting by
-editing your :doc:`configuration file </reference/config>`. Put ``chroma`` on
-your ``plugins:`` line. With that, beets will use fingerprinting the next time
-you run ``beet import``.
+Once you have all the dependencies sorted out, enable the plugin in your
+configuration (see :ref:`using-plugins`) to benefit from fingerprinting the
+next time you run ``beet import``.
 
 You can also use the ``beet fingerprint`` command to generate fingerprints for
 items already in your library. (Provide a query to fingerprint a subset of your
@@ -101,16 +100,16 @@ library.) The generated fingerprints will be stored in the library database.
 If you have the ``import.write`` config option enabled, they will also be
 written to files' metadata.
 
-You can disable fingerprinting on import by setting the ``auto`` option to
-false, like so::
-
-    chroma:
-        auto: no
-
 .. _submitfp:
 
+Configuration
+-------------
+
+The only option is **auto**, set it to 'no' to disable fingerprinting on
+import.
+
 Submitting Fingerprints
-'''''''''''''''''''''''
+-----------------------
 
 You can help expand the `Acoustid`_ database by submitting fingerprints for the
 music in your collection. To do this, first `get an API key`_ from the Acoustid

docs/plugins/convert.rst

@@ -10,8 +10,8 @@ line.
 Installation
 ------------
 
-Enable the ``convert`` plugin in your configuration (see
-:doc:`/plugins/index`).  By default, the plugin depends on `FFmpeg`_ to
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`). By default, the plugin depends on `FFmpeg`_ to
 transcode the audio, so you might want to install it.
 
 .. _FFmpeg: http://ffmpeg.org
@@ -50,35 +50,37 @@ them.
 Configuration
 -------------
 
-The plugin offers several configuration options, all of which live under the
-``convert:`` section:
+Available options :
 
-* ``dest`` sets the directory the files will be converted (or copied) to.
-  A destination is required---you either have to provide it in the config file
-  or on the command-line using the ``-d`` flag.
-* ``embed`` indicates whether or not to embed album art in converted items.
-  Default: true.
-* If you set ``max_bitrate``, all lossy files with a higher bitrate will be
-  transcoded and those with a lower bitrate will simply be copied. Note that
-  this does not guarantee that all converted files will have a lower
-  bitrate---that depends on the encoder and its configuration.
-* ``auto`` gives you the option to import transcoded versions of your files
+- ``auto`` gives you the option to import transcoded versions of your files
   automatically during the ``import`` command. With this option enabled, the
   importer will transcode all non-MP3 files over the maximum bitrate before
   adding them to your library.
-* ``quiet`` mode prevents the plugin from announcing every file it processes.
-  Default: false.
-* ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg vorbis,
-  etc, are never converted, as converting lossy files to other lossy codecs will
-  decrease quality further. If set to true, lossy files are always copied.
-  Default: false
-* ``paths`` lets you specify the directory structure and naming scheme for the
+  Default: ``no``.
+- ``dest`` sets the directory the files will be converted (or copied) to.
+  A destination is required---you either have to provide it in the config file
+  or on the command-line using the ``-d`` flag.
+- ``embed`` indicates whether or not to embed album art in converted items.
+  Default: ``yes``.
+- ``max_bitrate``: all lossy files with a higher bitrate will be
+  transcoded and those with a lower bitrate will simply be copied. Note that
+  this does not guarantee that all converted files will have a lower
+  bitrate---that depends on the encoder and its configuration.
+- ``never_convert_lossy_files`` means that lossy codecs, such as mp3, ogg
+  vorbis, etc, are never converted, as converting lossy files to other lossy
+  codecs will decrease quality further. If set to ``yes``, lossy files are
+  always copied.
+  Default: ``no``
+- ``paths`` lets you specify the directory structure and naming scheme for the
   converted files. Use the same format as the top-level ``paths`` section (see
-  :ref:`path-format-config`). By default, the plugin reuses your top-level
-  path format settings.
-* Finally, ``threads`` determines the number of threads to use for parallel
-  encoding. By default, the plugin will detect the number of processors
-  available and use them all.
+  :ref:`path-format-config`).
+  By default, the plugin reuses your top-level path format settings.
+- ``quiet`` mode prevents the plugin from announcing every file it processes.
+  Default: ``false``.
+- ``threads`` determines the number of threads to use for parallel
+  encoding.
+  By default, the plugin will detect the number of processors available and use
+  them all.
 
 .. _convert-format-config:
 
@@ -114,7 +116,7 @@ formats: `mp3`, `alac`, `flac`, `aac`, `opus`, `ogg`, `wmv`. For
 details have a look at the output of ``beet config -d``.
 
 For a one-command-fits-all solution use the ``convert.command`` and
-``convert.extension`` options. If these are set the formats are ignored
+``convert.extension`` options. If these are set, the formats are ignored
 and the given command is used for all conversions.::
 
     convert:

docs/plugins/discogs.rst

@@ -9,8 +9,8 @@ include matches from the `Discogs`_ database.
 Installation
 ------------
 
-First, enable the ``discogs`` plugin (see :doc:`/plugins/index`). Then,
-install the `discogs-client`_ library by typing::
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`). Then, install the `discogs-client`_ library by typing::
 
     pip install discogs-client
 

docs/plugins/duplicates.rst

@@ -4,43 +4,20 @@ Duplicates Plugin
 This plugin adds a new command, ``duplicates`` or ``dup``, which finds
 and lists duplicate tracks or albums in your collection.
 
-Installation
-------------
+Usage
+-----
 
-Enable the plugin by putting ``duplicates`` on your ``plugins`` line in
-your :doc:`config file </reference/config>`::
-
-    plugins: duplicates
-
-Configuration
--------------
+To use the plugin, first enable it in your configuration (see
+:ref:`using-plugins`).
 
 By default, the ``beet duplicates`` command lists the names of tracks
 in your library that are duplicates. It assumes that Musicbrainz track
 and album ids are unique to each track or album. That is, it lists
 every track or album with an ID that has been seen before in the
 library.
-
 You can customize the output format, count the number of duplicate
 tracks or albums, and list all tracks that have duplicates or just the
-duplicates themselves. These options can either be specified in the
-config file::
-
-    duplicates:
-	checksum: no
-	copy: no
-	keys: mb_trackid album
-        album: no
-        count: no
-        delete: no
-        format: "$albumartist - $album - $title"
-        full: no
-        move: no
-        path: no
-        tag: no
-	
-	
-or on the command-line::
+duplicates themselves via command-line switches ::
 
   -h, --help            show this help message and exit
   -f FMT, --format=FMT  print with custom format
@@ -56,83 +33,50 @@ or on the command-line::
   -p, --path            print paths for matched items or albums
   -t TAG, --tag=TAG     tag matched items with 'k=v' attribute
 
+Configuration
+-------------
 
-format
-~~~~~~
+Available options (mirroring the CLI ones) :
 
-The ``format`` option (default: :ref:`list_format_item`) lets you
-specify a specific format with which to print every track or
-album. This uses the same template syntax as beets’ :doc:`path formats
-</reference/pathformat>`.  The usage is inspired by, and therefore
-similar to, the :ref:`list <list-cmd>` command.
-
-path
-~~~~
-
-Convenience wrapper for ``-f \$path``.
-
-count
-~~~~~
-
-The ``count`` option (default: false) prints a count of duplicate
-tracks or albums, with ``format`` hard-coded to ``$albumartist -
-$album - $title: $count`` or ``$albumartist - $album: $count`` (for
-the ``-a`` option).
-
-album
-~~~~~
-
-The ``album`` option (default: false) lists duplicate albums instead
-of tracks.
-
-full
-~~~~
-
-The ``full`` option (default: false) lists every track or album that
-has duplicates, not just the duplicates themselves.
-
-keys
-~~~~
-
-The ``keys`` option (default: ``[mb_trackid, mb_albumid]``) defines in which track
-or album fields duplicates are to be searched. By default, the plugin
-uses the musicbrainz track and album IDs for this purpose. Using the
-``keys`` option (as a YAML list in the configuration file, or as
-space-delimited strings in the command-line), you can extend this behavior
-to consider other attributes.
-
-checksum
-~~~~~~~~
-
-The ``checksum`` option (default: ``ffmpeg -i {file} -f crc -``) enables the use of
-any arbitrary command to compute a checksum of items. It overrides the ``keys``
-option the first time it is run; however, because it caches the resulting checksums
-as ``flexattrs`` in the database, you can use
-``--keys=name_of_the_checksumming_program any_other_keys`` the second time around.
-
-copy
-~~~~
-
-The ``copy`` option (default: ``no``) takes a destination base directory into which
-it will copy matched items.
-
-move
-~~~~
-
-The ``move`` option (default: ``no``) takes a destination base directory into which
-it will move matched items.
-
-delete
-~~~~~~
-
-The ``delete`` option (default: ``no``) removes matched items from the library
-and from the disk.
-
-tag
-~~~
-
-The ``tag`` option (default: ``no``) takes a ``key=value`` string, and adds a new
-``key`` attribute with ``value`` value as a flexattr to the database.
+- ``album`` lists duplicate albums instead of tracks.
+  Default: ``no``.
+- ``checksum`` enables the use of any arbitrary command to compute a checksum
+  of items. It overrides the ``keys`` option the first time it is run; however,
+  because it caches the resulting checksum as ``flexattrs`` in the database,
+  you can use ``--keys=name_of_the_checksumming_program any_other_keys`` (or
+  set configuration ``keys``option) the second time around.
+  Default: ``ffmpeg -i {file} -f crc -``.
+- ``copy`` takes a destination base directory into which it will copy matched
+  items.
+  Default: ``no``.
+- `count` prints a count of duplicate tracks or albums, with ``format``
+  hard-coded to ``$albumartist - $album - $title: $count`` or ``$albumartist -
+  $album: $count`` (for the ``-a`` option).
+  Default: ``no``.
+- ``delete`` removes matched items from the library and from the disk.
+  Default: ``no``
+- `format` lets you specify a specific format with which to print every track
+  or album. This uses the same template syntax as beets
+  ’:doc:`path formats</reference/pathformat>`.  The usage is inspired by, and
+  therefore similar to, the :ref:`list <list-cmd>` command.
+  Default: :ref:`list_format_item`
+- ``full`` lists every track or album that has duplicates, not just the
+  duplicates themselves.
+  Default: ``no``.
+- ``keys`` defines in which track or album fields duplicates are to be
+  searched. By default, the plugin uses the musicbrainz track and album IDs for
+  this purpose. Using the ``keys`` option (as a YAML list in the configuration
+  file, or as space-delimited strings in the command-line), you can extend this
+  behavior to consider other attributes.
+  Default: ``[mb_trackid, mb_albumid]``
+- ``move`` takes a destination base directory into which it will move matched
+  items.
+  Default: ``no``.
+- `path` is a convenience wrapper for ``-f \$path``.
+  Default: ``no``.
+- ``tag`` takes a ``key=value`` string, and adds a new ``key`` attribute with
+  ``value`` value as a flexattr to the database.
+  Default: ``no``.
 
 Examples
 --------
@@ -150,7 +94,8 @@ Print out a unicode histogram of duplicate track years using `spark`_::
   beet duplicates -f '$year' | spark
   ▆▁▆█▄▇▇▄▇▇▁█▇▆▇▂▄█▁██▂█▁▁██▁█▂▇▆▂▇█▇▇█▆▆▇█▇█▇▆██▂▇
 
-Print out a listing of all albums with duplicate tracks, and respective counts::
+Print out a listing of all albums with duplicate tracks, and respective
+counts::
 
   beet duplicates -ac
 
@@ -162,8 +107,8 @@ Get tracks with the same title, artist, and album::
 
   beet duplicates -k title albumartist album
 
-Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report back
-duplicates based on those values::
+Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report
+back duplicates based on those values::
 
   beet dup -C 'ffmpeg -i {file} -f crc -'
   beet dup -C 'md5sum {file}'
@@ -181,12 +126,8 @@ Delete items (careful!), if they're Nickelback::
   beet duplicates --delete --keys albumartist albumartist:nickelback
 
 Tag duplicate items with some flag::
-  
+
   beet duplicates --tag dup=1
 
-TODO
-----
-
-- better duplicate disambiaguation strategies (eg, based on bitrate, etc)
 
 .. _spark: https://github.com/holman/spark

docs/plugins/echonest.rst

@@ -41,63 +41,44 @@ algorithms supported by the Echo Nest. Please note that fingerprinting is not
 required if ``upload`` and ``convert`` is enabled, which is the default (but
 it can be faster than uploading).
 
+Finally, to use the plugin, enable it in your configuration (see
+:ref:`using-plugins`).
+
 .. _pip: http://pip.openplans.org/
 .. _FFmpeg: http://ffmpeg.org
 .. _ENMFP: http://static.echonest.com/ENMFP_codegen.zip
 .. _Echoprint: http://echoprint.me
 
 
-Configuring
------------
+Configuration
+-------------
 
-Beets includes its own Echo Nest API key, but you can `apply for your own`_ for
-free from the Echo Nest.  To specify your own API key, add the key to your
-:doc:`configuration file </reference/config>` as the value for ``apikey`` under
-the key ``echonest`` like so::
+Available options :
 
-    echonest:
-        apikey: YOUR_API_KEY
-
-In addition, the ``auto`` config option lets you disable automatic metadata
-fetching during import. To do so, add this to your ``config.yaml``::
-
-    echonest:
-        auto: no
-
-The ``echonest`` plugin tries to upload files to the Echo Nest server if it
-can not be identified by other means.  If you don't want that, disable the
-``upload`` config option like so::
-
-    echonest:
-        upload: no
-
-The Echo Nest server only supports a limited range of file formats.  The plugin
-automatically converts unsupported files to ``ogg``.  If you don't want that,
-disable the ``convert`` config option like so::
-
-    echonest:
-        convert: no
-
-The Echo Nest server does not allow uploading of files with sizes greater than
-50MB. The plugin automatically truncates large files to their first 5
-minutes. If you don't want that, disable the ``truncate`` config option like
-so::
-
-    echonest:
-        truncate: no
-
-To enable fingerprinting, you'll need to tell the plugin where to find the
-Echoprint or ENMFP codegen binary. Use the ``codegen`` key under the
-``echonest`` section like so::
-
-    echonest:
-        codegen: /usr/bin/echoprint-codegen
+- ``apikey``: set this option to specify your own EchoNest API key.
+  You can `apply for your own`_ for free from the EchoNest.
+  Default: beets includes its own Echo Nest API key.
+- ``auto``: set it to ``no`` to disable automatic metadata fetching during
+  import.
+  Default: ``yes``.
+- ``codegen``: Echoprint or ENMFP codegen binary path.
+  Default: ``None``
+- ``convert``: because the Echo Nest server only supports a limited range of
+  file formats, the plugin automatically converts unsupported files to ``ogg``.
+  Default: ``yes``.
+- ``truncate``: automatically truncates large files to their first 5 minutes
+  before uploading them to The Echo Nest server (as files with sizes greater
+  than 50MB are rejected).
+  Default: ``yes``.
+- ``upload``: send files to the Echo Nest server if it can not be identified by
+  other means.
+  Default: ``yes``.
 
 .. _apply for your own: http://developer.echonest.com/account/register
 
 Running Manually
 ----------------
 
-In addition to running automatically on import, the plugin can also be run manually
-from the command line. Use the command ``beet echonest [QUERY]`` to fetch
-acoustic attributes for albums matching a certain query.
+In addition to running automatically on import, the plugin can also be run
+manually from the command line. Use the command ``beet echonest [QUERY]`` to
+fetch acoustic attributes for albums matching a certain query.

docs/plugins/echonest_tempo.rst

@@ -1,5 +1,5 @@
-EchoNest Tempo Plugin
-=====================
+Echo Nest Tempo Plugin
+======================
 
 .. note::
 
@@ -16,33 +16,27 @@ field) from the `Echo Nest API`_.
 Installing Dependencies
 -----------------------
 
-This plugin requires the pyechonest library in order to talk to the EchoNest 
+This plugin requires the pyechonest library in order to talk to the EchoNest
 API.
 
 There are packages for most major linux distributions, you can download the
-library from the Echo Nest, or you can install the library from `pip`_, 
+library from the Echo Nest, or you can install the library from `pip`_,
 like so::
 
     $ pip install pyechonest
 
 .. _pip: http://pip.openplans.org/
 
-Configuring
------------
+Configuration
+-------------
 
-Beets includes its own Echo Nest API key, but you can `apply for your own`_ for
-free from the EchoNest.  To specify your own API key, add the key to your
-:doc:`configuration file </reference/config>` as the value for ``apikey`` under
-the key ``echonest_tempo`` like so::
+Available options:
 
-    echonest_tempo:
-        apikey: YOUR_API_KEY
-
-In addition, the ``autofetch`` config option lets you disable automatic tempo
-fetching during import. To do so, add this to your ``config.yaml``::
-
-    echonest_tempo:
-        auto: no
+- ``auto``: set to ``no``to disable automatic tempo fetching during import.
+  Default: ``true``.
+- ``apikey``: set this option to specify your own EchoNest API key.
+  You can `apply for your own`_ for free from the EchoNest.
+  Default: beets includes its own Echo Nest API key.
 
 .. _apply for your own: http://developer.echonest.com/account/register
 
@@ -61,12 +55,12 @@ This behavior can be disabled with the ``autofetch`` config option (see below).
 Fetching Tempo Manually
 -----------------------
 
-The ``tempo`` command provided by this plugin fetches tempos for 
-items that match a query (see :doc:`/reference/query`). For example, 
-``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the 
-appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get 
-tempos for all my tracks by that band, and ``beet tempo`` will get tempos for 
-my entire library. The tempos will be added to the beets database and, if 
+The ``tempo`` command provided by this plugin fetches tempos for
+items that match a query (see :doc:`/reference/query`). For example,
+``beet tempo magnetic fields absolutely cuckoo`` will get the tempo for the
+appropriate Magnetic Fields song, ``beet tempo magnetic fields`` will get
+tempos for all my tracks by that band, and ``beet tempo`` will get tempos for
+my entire library. The tempos will be added to the beets database and, if
 ``import.write`` is on, embedded into files' metadata.
 
 The ``-p`` option to the ``tempo`` command makes it print tempos out to the

docs/plugins/embedart.rst

@@ -7,18 +7,14 @@ You might want to embed the album art directly into each file's metadata. While
 this will take more space than the external-file approach, it is necessary for
 displaying album art in some media players (iPods, for example).
 
-This plugin was added in beets 1.0b8.
+Usage
+-----
 
-Embedding Art Automatically
----------------------------
-
-To automatically embed discovered album art into imported files, just enable the
-plugin (see :doc:`/plugins/index`). You'll also want to enable the
+To automatically embed discovered album art into imported files, just enable
+the plugin (see :doc:`/plugins/index`). You'll also want to enable the
 :doc:`/plugins/fetchart` to obtain the images to be embedded. Art will be
 embedded after each album is added to the library.
 
-This behavior can be disabled with the ``auto`` config option (see below).
-
 .. _image-similarity-check:
 
 Image Similarity
@@ -40,6 +36,34 @@ number, the more similar the images must be.
 
 This feature requires `ImageMagick`_.
 
+Configuration
+-------------
+
+Available options :
+
+- ``auto`` option lets you disable automatic album art embedding when set to
+  ``no``.
+  Default: ``true``
+- ``compare_threshold``: how similar must candidate art be regarding to
+  embedded art to be written to the file (see :ref:`image-similarity-check`).
+  Default: ``0`` (disabled).
+- ``ifempty``: set to 'yes' to avoid embedding album art for files that already
+  have one.
+  Default: ``no``.
+- ``maxwidth`` defines a maximum width to downscale images before embedding
+  them (the original image file is not altered). The resize operation reduces
+  image width to ``maxwidth`` pixels. The height is recomputed so that the
+  aspect ratio is preserved. See also :ref:`image-resizing` for further caveats
+  about image resizing.
+  Default: ``0`` (disabled).
+
+Note: ``compare_threshold`` option requires `ImageMagick`_ , ``maxwidth``
+requires `ImageMagick`_ or `PIL`_
+
+.. _PIL: http://www.pythonware.com/products/pil/
+.. _ImageMagick: http://www.imagemagick.org/
+.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/
+
 Manually Embedding and Extracting Art
 -------------------------------------
 
@@ -59,31 +83,3 @@ embedded album art:
 
 * ``beet clearart QUERY``: removes all embedded images from all items matching
   the query. (Use with caution!)
-
-Configuring
------------
-
-The ``auto`` option  lets you disable automatic album art embedding.
-To do so, add this to your ``config.yaml``::
-
-    embedart:
-        auto: no
-
-A maximum image width can be configured as ``maxwidth`` to downscale images
-before embedding them (the original image file is not altered). The resize
-operation reduces image width to ``maxwidth`` pixels. The height is recomputed
-so that the aspect ratio is preserved. `PIL`_ or `ImageMagick`_ is required to
-use the ``maxwidth`` config option. See also :ref:`image-resizing` for further
-so that the aspect ratio is preserved.
-
-The ``compare_threshold`` option defines how similar must candidate art be
-regarding to embedded art to be written to the file (see
-:ref:`image-similarity-check`). The default is 0 (no similarity check).
-Requires `ImageMagick`_.
-
-To avoid embedding album art for files that already have album art, set the
-``ifempty`` config option to ``yes``.
-
-.. _PIL: http://www.pythonware.com/products/pil/
-.. _ImageMagick: http://www.imagemagick.org/
-.. _PHASH: http://www.fmwconcepts.com/misc_tests/perceptual_hash_test_results_510/

docs/plugins/fetchart.rst

@@ -13,8 +13,8 @@ The plugin uses `requests`_ to fetch album art from the Web.
 
 .. _requests: http://docs.python-requests.org/en/latest/
 
-Fetching Album Art During Import
---------------------------------
+Usage
+-----
 
 When the plugin is enabled, it automatically gets album art for every album
 you import.
@@ -23,11 +23,38 @@ By default, beets stores album art image files alongside the music files for an
 album in a file called ``cover.jpg``. To customize the name of this file, use
 the :ref:`art-filename` config option.
 
-To disable automatic art downloading, just put this in your configuration
-file::
+Configuration
+-------------
+
+Available options :
+
+- ``auto``: set it to ``no`` to disable automatic album art fetching during
+  import.
+  Default: ``yes``.
+- ``cautious``: pick only trusted album arts by ignoring filenames that do not
+  contain one of ``cover_names`` keywords.
+  Default: ``no``.
+- ``cover_names``: image filenames that contain word(s) of this list will be
+  picked primarily.
+  Default: ``['cover', 'front', 'art', 'album', 'folder']``.
+- ``google_search``: set it to `yes` gather images from Google Images search.
+  Default: ``no``.
+- ``maxwidth``: maximum image width to downscale fetched images if they are
+  too big. The resize operation reduces image width to ``maxwidth`` pixels. The
+  height is recomputed so that the aspect ratio is preserved.
+- ``remote_priority``: query remote sources every time and use local image only
+  as fallback.
+  Default: ``no``, remote (Web) art sources are only queried if no local art is
+  found in the filesystem.
+
+Here's an example that makes plugin select only images that contain *front* or
+*back* keywords in their filenames::
 
     fetchart:
-        auto: no
+        cautious: true
+        cover_names: front back
+
+
 
 Manually Fetching Album Art
 ---------------------------
@@ -47,11 +74,6 @@ be processed; otherwise, the command processes every album in your library.
 Image Resizing
 --------------
 
-A maximum image width can be configured as ``maxwidth`` to downscale fetched
-images if they are too big. The resize operation reduces image width to
-``maxwidth`` pixels. The height is recomputed so that the aspect ratio is
-preserved.
-
 Beets can resize images using `PIL`_, `ImageMagick`_, or a server-side resizing
 proxy. If either PIL or ImageMagick is installed, beets will use those;
 otherwise, it falls back to the resizing proxy. If the resizing proxy is used,
@@ -79,19 +101,6 @@ file whose name contains "cover", "front", "art", "album" or "folder", but in
 the absence of well-known names, it will use any image file in the same folder
 as your music files.
 
-You can change the list of filename keywords using the ``cover_names`` config
-option. Or, to use *only* filenames containing the keywords and not fall back
-to any image, set ``cautious`` to true. For example::
-
-    fetchart:
-        cautious: true
-        cover_names: front back
-
-By default, remote (Web) art sources are only queried if no local art is found
-in the filesystem. To query remote sources every time, set the
-``remote_priority`` configuration option to true, which will cause beets to
-prefer remote cover art over any local image files.
-
 When you choose to apply changes during an import, beets will search for art as
 described above.  For "as-is" imports (and non-autotagged imports using the
 ``-A`` flag), beets only looks for art on the local filesystem.
@@ -106,11 +115,6 @@ unlikely).
 
 .. _Google Images: http://images.google.com/
 
-To enable gathering art from Google, enable the ``google_search`` option in
-your config file::
-
-    fetchart:
-        google_search: true
 
 Embedding Album Art
 -------------------

docs/plugins/fromfilename.rst

@@ -9,6 +9,4 @@ When you attempt to import a track that's missing a title, this plugin will
 look at the track's filename and guess its track number, title, and artist.
 These will be used to search in MusicBrainz and match track ordering.
 
-To use the plugin, just enable it by putting ``fromfilename`` on the
-``plugins:`` line in your config file. There are currently no configuration
-options.
+To use the plugin, enable it in your configuration (see :ref:`using-plugins`).

docs/plugins/ftintitle.rst

@@ -1,7 +1,7 @@
 FtInTitle Plugin
 ================
 
-The ``ftintitle`` plugin automatically moved "featured" artists from the
+The ``ftintitle`` plugin automatically move "featured" artists from the
 ``artist`` field to the ``title`` field.
 
 According to `MusicBrainz style`_, featured artists are part of the artist
@@ -10,17 +10,30 @@ tracks in your library like "Tellin' Me Things" by the artist "Blakroc feat.
 RZA". If you prefer to tag this as "Tellin' Me Things feat. RZA" by "Blakroc",
 then this plugin is for you.
 
-To use the plugin, just enable it and run the command::
+To use the plugin, enable it in your configuration (see :ref:`using-plugins`).
+
+Configuration
+-------------
+
+Available options :
+
+- ``auto``: set it to ``no`` to disable plugin during import.
+  Default: ``yes``.
+- ``drop``: remove featured artists entirely instead of adding them to the
+  title field.
+  Default: ``no``
+
+Running manually
+----------------
+
+From the command line, type::
 
     $ beet ftintitle [QUERY]
 
 The query is optional; if it's left off, the transformation will be applied to
 your entire collection.
 
-If you prefer to remove featured artists entirely instead of adding them to
-the title field, either use the ``-d`` flag to the command or set the
-``ftintitle.drop`` config option.
-
-To disable this plugin on import, set the ``auto`` config option to false.
+Use the ``-d``flag to remove featured artists (equivalent of the ``drop``
+option).
 
 .. _MusicBrainz style: http://musicbrainz.org/doc/Style

docs/plugins/fuzzy.rst

@@ -1,25 +1,23 @@
 Fuzzy Search Plugin
 ===================
 
-The ``fuzzy`` plugin provides a prefixed query that search you library using
+The ``fuzzy`` plugin provides a prefixed query that searches you library using
 fuzzy pattern matching. This can be useful if you want to find a track with
 complicated characters in the title.
 
-First, enable the plugin named ``fuzzy`` (see :doc:`/plugins/index`).
+First, enable the plugin named ``fuzzy`` (see :ref:`using-plugins`).
 You'll then be able to use the ``~`` prefix to use fuzzy matching::
 
     $ beet ls '~Vareoldur'
     Sigur Rós - Valtari - Varðeldur
 
-The plugin provides config options that let you choose the prefix and the
-threshold.::
+Configuration
+-------------
 
-    fuzzy:
-        threshold: 0.8
-        prefix: '@'
+Available options :
 
-A threshold value of 1.0 will show only perfect matches and a value of 0.0
-will match everything.
-
-The default prefix ``~`` needs to be escaped or quoted in most shells. If this
-bothers you, you can change the prefix in your config file.
+- ``threshold``: a value of 1.0 will show only perfect matches and a value of
+  0.0 will match everything.
+  Default: ``0.7``
+- ``prefix``: character to use to designate fuzzy queries.
+  Default: ``~`` (needs to be escaped or quoted in most shells)

docs/plugins/ihate.rst

@@ -6,18 +6,26 @@ import or warn you about them. You specify queries (see
 :doc:`/reference/query`) and the plugin skips (or warns about) albums or items
 that match any query.
 
-To use the plugin, first enable it in your configuration (see
-:ref:`using-plugins`). Then, add an ``ihate:`` section to your configuration
-file::
+To use the plugin, enable it in your configuration (see
+:ref:`using-plugins`).
+
+Configuration
+-------------
+
+Available options :
+
+- ``skip``: never import matches. Default: ``[]``
+- ``warn``: print a warning message for matches. Default: ``[]``
+
+
+Here's an example ::
 
     ihate:
-        # Print a warning message for these.
         warn:
             - artist:rnb
             - genre: soul
             # Only warn about tribute albums in rock genre.
             - genre:rock album:tribute
-        # Never import any of this.
         skip:
             - genre::russian\srock
             - genre:polka

docs/plugins/importadded.rst

@@ -16,10 +16,8 @@ The ``item.added`` field is populated as follows:
   set to the oldest mtime of the files in the album before they were imported.
   The mtime of album directories is ignored.
 
-This plugin can optionally be configured to also preserve mtimes::
-
-    importadded:
-        preserve_mtimes: yes # default: no
+This plugin can optionally be configured to also preserve mtimes using the
+``preserve_mtimes`` option.
 
 File modification times are preserved as follows:
 
@@ -32,7 +30,15 @@ File modification times are preserved as follows:
 Note that there is no ``album.mtime`` field in the database and that the mtime
 of album directories on disk aren't preserved.
 
+Configuration
+-------------
+
+Available option:
+
+- ``preserve_mtimes``: Default: ``no``
+
 Reimport
 --------
 
-This plugin will skip reimported singleton items and reimported albums and all of their items.
+This plugin will skip reimported singleton items and reimported albums and all
+of their items.

docs/plugins/importfeeds.rst

@@ -1,30 +1,41 @@
 ImportFeeds Plugin
 ==================
 
-The ``importfeeds`` plugin helps you keep track of newly imported music in your library.
+The ``importfeeds`` plugin helps you keep track of newly imported music in your
+library.
 
-To use the plugin, just put ``importfeeds`` on the ``plugins`` line in your
-:doc:`configuration file </reference/config>`. Then set a few options under the
-``importfeeds:`` section in the config file.
+To use the plugin, enable it in your configuration (see :ref:`using-plugins`).
 
-The ``dir`` configuration option can be set to specify another folder
-than the default library directory. This is where your playlist will be created.
+Configuration
+-------------
 
-The ``relative_to`` configuration option can be set to make the m3u paths
-relative to another folder than where the playlist is being written. If you're
-using importfeeds to generate a playlist for MPD, you should set this to the
-root of your music library.
+Available options :
 
-The ``absolute_path`` configuration option can be set to use absolute paths
-instead of relative paths. Some applications may need this to work properly.
+- ``absolute_path`` option can be set to use absolute paths instead of relative
+  paths. Some applications may need this to work properly.
+  Default: ``no``.
+- ``dir`` option can be set to specify another output folder than the default
+  library directory.
+  Default: ``None``.
+- ``formats`` option can be set to select desired output type(s):
 
-Four different types of outputs are available. Specify the ones you want to
-use by setting the ``formats`` parameter:
+    - ``m3u``: catalog the imports in a centralized playlist.
+    - ``m3u_multi``: create a new playlist for each import (uniquely named by
+      appending the date and track/album name).
+    - ``link``: create a symlink for each imported item. This is the
+      recommended setting to propagate beets imports to your iTunes library: just
+      drag and drop the ``dir`` folder on the iTunes dock icon.
+    - ``echo``: do not write a playlist file at all, but echo a list of new
+      file paths to the terminal.
 
-- ``m3u``: catalog the imports in a centralized playlist. By default, the playlist is named ``imported.m3u``. To use a different file, just set the ``m3u_name`` parameter inside the ``importfeeds`` config section.
-- ``m3u_multi``: create a new playlist for each import (uniquely named by appending the date and track/album name).
-- ``link``: create a symlink for each imported item. This is the recommended setting to propagate beets imports to your iTunes library: just drag and drop the ``dir`` folder on the iTunes dock icon.
-- ``echo``: do not write a playlist file at all, but echo a list of new file paths to the terminal.
+  Default: ``[]``.
+- ``m3u_name``: playlist name used by ``m3u`` format.
+  Default: ``imported.m3u``.
+- ``relative_to`` option can be set to make the m3u paths relative to another
+  folder than where the playlist is being written. If you're using importfeeds
+  to generate a playlist for MPD, you should set this to the root of your music
+  library.
+  Default: ``None``.
 
 Here's an example configuration for this plugin::
 

docs/plugins/index.rst

@@ -15,12 +15,19 @@ Using Plugins
 To use one of the plugins included with beets (see the rest of this page for a
 list), just use the `plugins` option in your :doc:`config.yaml </reference/config>`: file, like so::
 
-    plugins: inline discogs web
+    plugins: inline convert web
 
 The value for `plugins` can be a space-separated list of plugin names or a
 YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
 by typing ``beet version``.
 
+Each plugin has its own set of options that can be defined in a section bearing its name::
+
+    plugins: inline convert web
+
+    convert:
+        auto: true
+
 .. toctree::
    :hidden:
 

docs/plugins/info.rst

@@ -5,7 +5,8 @@ The ``info`` plugin provides a command that dumps the current tag values for
 any file format supported by beets. It works like a supercharged version of
 `mp3info`_ or `id3v2`_.
 
-Enable the plugin and then type::
+Enable the plugin in your configuration (see :ref:`using-plugins`) and then
+ type::
 
     $ beet info /path/to/music.flac
 

docs/plugins/inline.rst

@@ -6,9 +6,8 @@ it, you can define template fields in your beets configuration file and refer
 to them from your template strings in the ``paths:`` section (see
 :doc:`/reference/config/`).
 
-To use inline field definitions, first enable the plugin by putting ``inline``
-on your ``plugins`` line in your configuration file. Then, make a
-``item_fields:`` block in your config file. Under this key, every line defines a
+To use the plugin, enable it in your configuration (see :ref:`using-plugins`).
+Then, make a `item_fields:`` block in your config file. Under this key, every line defines a
 new template field; the key is the name of the field (you'll use the name to
 refer to the field in your templates) and the value is a Python expression or
 function body. The Python code has all of a track's fields in scope, so you can
@@ -42,7 +41,7 @@ a result for the value of the path field, like so::
     item_fields:
         filename: |
             import os
-            from beets.util import bytestring_path 
+            from beets.util import bytestring_path
             return bytestring_path(os.path.basename(path))
 
 You might want to use the YAML syntax for "block literals," in which a leading

docs/plugins/keyfinder.rst

@@ -3,26 +3,28 @@ Key Finder Plugin
 
 The `keyfinder` plugin uses the `KeyFinder`_ program to detect the
 musical key of track from its audio data and store it in the
-`initial_key` field of you database.  If enabled, it does so
+'initial_key' field of you database.  It does so
 automatically when importing music or through the ``beet keyfinder
 [QUERY]`` command.
 
-There are a couple of configuration options to customize the behavior of
-the plugin. By default they are::
+To use the plugin, enable it in your configuration (see
+:ref:`using-plugins`).
 
-    keyfinder:
-        bin: KeyFinder
-        auto: yes
-        overwrite: no
+Configuration
+-------------
 
-* ``bin``: The name of the `KeyFinder` program on your system or
+Available options:
+
+- ``bin``: The name of the `KeyFinder` program on your system or
   a path to the binary. If you installed the `KeyFinder`_ GUI on a Mac, for
   example, you want something like
   ``/Applications/KeyFinder.app/Contents/MacOS/KeyFinder``.
-* ``auto``: If set to `yes`, the plugin will analyze every file on
+  Default: ``KeyFinder``.
+- ``auto``: If set to `yes`, the plugin will analyze every file on
   import. Otherwise, you need to use the ``beet keyfinder`` command
-  explicitly.
-* ``overwrite``: If set to `no`, the import hook and the command will skip
-  any file that already has an `initial_key` in the database.
+  explicitly. Default: ``yes``.
+- ``overwrite``: If set to ``no``, the import hook and the command will skip
+  any file that already has an 'initial_key' in the database.
+  Default: ``no``.
 
 .. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/

docs/plugins/lastgenre.rst

@@ -4,30 +4,31 @@ LastGenre Plugin
 The MusicBrainz database `does not contain genre information`_. Therefore, when
 importing and autotagging music, beets does not assign a genre.  The
 ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres
-to your albums and items. The plugin is included with beets as of version
-1.0b11.
+to your albums and items.
 
 .. _does not contain genre information:
     http://musicbrainz.org/doc/General_FAQ#Why_does_MusicBrainz_not_support_genre_information.3F
 .. _Last.fm: http://last.fm/
 
+Installation
+------------
+
 The plugin requires `pylast`_, which you can install using `pip`_ by typing::
 
     pip install pylast
 
-After you have pylast installed, enable the plugin by putting ``lastgenre`` on
-your ``plugins`` line in :doc:`config file </reference/config>`.
+After you have pylast installed, nable the plugin in your configuration (see
+:ref:`using-plugins`).
+
+Usage
+-----
 
 The plugin chooses genres based on a *whitelist*, meaning that only certain
 tags can be considered genres. This way, tags like "my favorite music" or "seen
 live" won't be considered genres. The plugin ships with a fairly extensive
-`internal whitelist`_, but you can set your own in the config file using the 
-``whitelist`` configuration value::
-
-    lastgenre:
-        whitelist: /path/to/genres.txt
-
-…or go for no whitelist altogether by setting the option to `false`.
+`internal whitelist`_, but you can set your own in the config file using the
+``whitelist`` configuration value or go for no whitelist altogether by setting
+the option to `false`.
 
 The genre list file should contain one genre per line. Blank lines are ignored.
 For the curious, the default genre list is generated by a `script that scrapes
@@ -38,79 +39,70 @@ Wikipedia`_.
 .. _script that scrapes Wikipedia: https://gist.github.com/1241307
 .. _internal whitelist: https://raw.githubusercontent.com/sampsyo/beets/master/beetsplug/lastgenre/genres.txt
 
-By default, beets will always fetch new genres, even if the files already have
-once. To instead leave genres in place in when they pass the whitelist, set
-the ``force`` option to `no`.
-
-If no genre is found, the file will be left unchanged. To instead specify a
-fallback genre, use the ``fallback`` configuration option. You can, of
-course, use the empty string as a fallback, like so::
-
-    lastgenre:
-        fallback: ''
-
-
 Canonicalization
-----------------
+^^^^^^^^^^^^^^^^
 
 The plugin can also *canonicalize* genres, meaning that more obscure genres can
 be turned into coarser-grained ones that are present in the whitelist. This
 works using a tree of nested genre names, represented using `YAML`_, where the
 leaves of the tree represent the most specific genres.
 
-To enable canonicalization, set the ``canonical`` configuration value::
-
-    lastgenre:
-        canonical: true
-
-Setting this value to `true` will use a built-in canonicalization
-tree. You can also set it to a path, just like the ``whitelist`` config value,
-to use your own tree.
-
 .. _YAML: http://www.yaml.org/
 
 
 Genre Source
-------------
+^^^^^^^^^^^^
 
 When looking up genres for albums or individual tracks, you can choose whether
 to use Last.fm tags on the album, the artist, or the track. For example, you
-might want all the albums for a certain artist to carry the same genre. Set the
-``source`` configuration value to "album", "track", or "artist", like so::
-
-    lastgenre:
-        source: artist
-
+might want all the albums for a certain artist to carry the same genre.
 The default is "album". When set to "track", the plugin will fetch *both*
 album-level and track-level genres for your music when importing albums.
 
 
 Multiple Genres
----------------
+^^^^^^^^^^^^^^^
 
 By default, the plugin chooses the most popular tag on Last.fm as a genre. If
 you prefer to use a *list* of popular genre tags, you can increase the number
-of the ``count`` config option::
-
-    lastgenre:
-        count: 3
+of the ``count`` config option.
 
 Lists of up to *count* genres will then be used instead of single genres. The
 genres are separated by commas by default, but you can change this with the
-``separator`` config option::
-
-    lastgenre:
-        separator: ' / '
+``separator`` config option.
 
 `Last.fm`_ provides a popularity factor, a.k.a. *weight*, for each tag ranging
 from 100 for the most popular tag down to 0 for the least popular.
 The plugin uses this weight to discard unpopular tags.  The default is to
 ignore tags with a weight less then 10. You can change this by setting
-the ``min_weight`` config option::
+the ``min_weight`` config option.
 
-    lastgenre:
-        min_weight: 15
+Configuration
+-------------
 
+Available options:
+
+- ``auto``: set it to ``no`` to disable automatic genre fetching during import.
+  Default: ``yes``.
+- ``canonical``: setting this value to ``true`` will use a built-in canonicalization
+  tree. You can also set it to a path, just like the ``whitelist`` config value,
+  to use your own tree. Default: ``no``
+- ``count``: number of genres to fetch. Default: ``1``
+- ``fallback``: by default, the file will be left unchanged when no genre is
+  found. Specify a string if you prefer to use a fallback genre. You can use the
+  empty string ``''` to reset the genre. Default: ``None``
+- ``force``: by default, beets will always fetch new genres, even if the files already have
+  once. To instead leave genres in place in when they pass the whitelist, set
+  the ``force`` option to ``no``. Default: ``yes``
+- ``min_weight``: minimum popularity factor below which genres are discarded.
+  Default: ``10``
+- ``source``: defines on which entity to perform Last.fm tags lookup. Can be
+  either ``artist``, ``album`` or ``track``. Default: ``album``
+- ``separator``: genres separator string
+  Default: ``u', '``
+- ``whitelist``: give it a custom genre list filepath or set it to 'yes' to use
+  internal whitelist. If set to 'no' then all genres are considered valids.
+  Default: ``yes``
 
 Running Manually
 ----------------

docs/plugins/lyrics.rst

@@ -12,14 +12,36 @@ and, optionally, the Google custom search API.
 Fetch Lyrics During Import
 --------------------------
 
-To automatically fetch lyrics for songs you import, just enable the plugin by
-putting ``lyrics`` on your config file's ``plugins`` line (see
-:doc:`/plugins/index`).  When importing new files, beets will now fetch lyrics
-for files that don't already have them. The lyrics will be stored in the beets
-database. If the ``import.write`` config option is on, then the lyrics will also
-be written to the files' tags.
+To automatically fetch lyrics for songs you import, enable the plugin in your
+configuration (see :ref:`using-plugins`).
+When importing new files, beets will now fetch lyrics for files that don't
+already have them. The lyrics will be stored in the beets database. If the
+``import.write`` config option is on, then the lyrics will also be written to
+the files' tags.
 
-This behavior can be disabled with the ``auto`` config option (see below).
+
+Configuration
+-------------
+
+Available options :
+
+- ``auto``: set it to ``no`` to disable automatic lyrics fetching during import.
+  Default: ``yes``.
+- ``fallback``: by default, the file will be left unchanged when no lyrics are
+  found. Use the empty string ``''`` to reset the genre in such a case.
+  Default: ``None``;
+- ``google_API_key``: your Google API key.
+  Default: ``None``;
+- ``google_engine_ID``: custom search engine to use.
+  Default: ``009217259823014548361:lndtuqkycfu``, beets custom search engine
+  that gathers list of sources known to be scrapeable.
+
+Here's an example of ``config.yaml``::
+
+    lyrics:
+      fallback: ''
+      google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
+      google_engine_ID: 009217259823014548361:lndtuqkycfu
 
 
 Fetching Lyrics Manually
@@ -39,26 +61,8 @@ console so you can view the fetched (or previously-stored) lyrics.
 The ``-f`` option forces the command to fetch lyrics, even for tracks that
 already have lyrics.
 
-
-Configuring
------------
-
-To disable automatic lyric fetching during import, set the ``auto`` option to
-false, like so::
-
-    lyrics:
-        auto: no
-
-By default, if no lyrics are found, the file will be left unchanged. To
-specify a placeholder for the lyrics tag when none are found, use the
-``fallback`` configuration option::
-
-    lyrics:
-        fallback: 'No lyrics found'
-
 .. _activate-google-custom-search:
 
-
 Activate Google custom search
 ------------------------------
 
@@ -78,12 +82,6 @@ default, beets use a list of sources known to be scrapeable.
 
 .. _define a custom search engine: http://www.google.com/cse/all
 
-Here's an example of ``config.yaml``::
-
-    lyrics:
-      google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
-      google_engine_ID: 009217259823014548361:lndtuqkycfu
-
 Note that the Google custom search API is limited to 100 queries per day.
 After that, the lyrics plugin will fall back on its other data sources.
 

docs/plugins/mbcollection.rst

@@ -6,7 +6,8 @@ maintain your `music collection`_ list there.
 
 .. _music collection: http://musicbrainz.org/doc/Collections
 
-To begin, just enable the ``mbcollection`` plugin (see :doc:`/plugins/index`).
+To begin, just enable the ``mbcollection`` plugin in your
+configuration (see :ref:`using-plugins`).
 Then, add your MusicBrainz username and password to your
 :doc:`configuration file </reference/config>` under a ``musicbrainz`` section::
 
@@ -19,16 +20,12 @@ command automatically adds all of your albums to the first collection it finds.
 If you don't have a MusicBrainz collection yet, you may need to add one to your
 profile first.
 
+Configuration
+-------------
+
+
 Automatically Update on Import
 ------------------------------
 
-You can also configure the plugin to automatically amend your MusicBrainz
-collection whenever you import a new album. To do this, first enable the
-plugin and add your MusicBrainz account as above.  Then, add ``mbcollection``
-section and enable the enable ``auto`` flag therein::
-
-    mbcollection:
-        auto: yes
-
-During future imports, your default collection will be updated with each
-imported album.
+mbcollection: if set to ``yes``, the plugin will automatically amend your
+MusicBrainz collection whenever you import a new album. Default: ``false``

docs/plugins/mbsync.rst

@@ -15,9 +15,9 @@ configuration.
 Usage
 -----
 
-Enable the plugin and then run ``beet mbsync QUERY`` to fetch updated metadata
-for a part of your collection (or omit the query to run over your whole
-library).
+Enable the plugin in your configuration (see :ref:`using-plugins`) and then
+run ``beet mbsync QUERY`` to fetch updated metadata for a part of your
+collection (or omit the query to run over your whole library).
 
 This plugin treats albums and singletons (non-album tracks) separately. It
 first processes all matching singletons and then proceeds on to full albums.

docs/plugins/missing.rst

@@ -7,58 +7,45 @@ tracks are missing. Listing missing files requires one network call to
 MusicBrainz. Merely counting missing files avoids any network calls.
 
 
-Installation
-------------
-
-Enable the plugin by putting ``missing`` on your ``plugins`` line in
-:doc:`config file </reference/config>`::
-
-    plugins:
-        missing
-        ...
-
-Configuration
--------------
+Usage
+------
 
+Add the ``missing`` plugin to your configuration (see :ref:`using-plugins`).
 By default, the ``beet missing`` command lists the names of tracks that your
-library is missing from each album. You can customize the output format, count
+library is missing from each album.
+You can customize the output format, count
 the number of missing tracks per album, or total up the number of missing
-tracks over your whole library. These options can either be specified in the
-config file::
-
-    missing:
-        format: $albumartist - $album - $title
-        count: no
-        total: no
-
-or on the command-line::
+tracks over your whole library, using command-line switches ::
 
       -f FORMAT, --format=FORMAT
                             print with custom FORMAT
       -c, --count           count missing tracks per album
       -t, --total           count total of missing tracks
 
+ ... or by editing corresponding options.
 
-format
-~~~~~~
+Configuration
+-------------
 
-The ``format`` option (default: :ref:`list_format_item`) lets you specify a
-specific format with which to print every track. This uses the same template
-syntax as beets’ :doc:`path formats </reference/pathformat>`.  The usage is
-inspired by, and therefore similar to, the :ref:`list <list-cmd>` command.
+Available options :
 
-count
-~~~~~
+- ``count`` prints a count of missing tracks per album, with ``format``
+  defaulting to ``$albumartist - $album: $missing``.
+  Default: ``no``.
+- ``format`` lets you specify a specific format with which to print every
+  track. This uses the same template syntax as beets’
+  :doc:`path formats </reference/pathformat>`. The usage is inspired by, and
+  therefore similar to, the :ref:`list <list-cmd>` command.
+  Default: :ref:`list_format_item`.
+- ``total` prints a single count of missing tracks in all albums.
+  Default: ``false``.
 
-The ``count`` option (default: false) prints a count of missing tracks
-per album, with ``format`` defaulting to ``$albumartist - $album:
-$missing``.
+Here's an example ::
 
-total
-~~~~~
-
-The ``total`` option (default: false) prints a single
-count of missing tracks in all albums
+    missing:
+        format: $albumartist - $album - $title
+        count: no
+        total: no
 
 Template Fields
 ---------------
@@ -94,9 +81,4 @@ Call this plugin from other beet commands::
 
   beet ls -a -f '$albumartist - $album: $missing'
 
-TODO
-----
-
-- Add caching.
-
 .. _spark: https://github.com/holman/spark

docs/plugins/mpdstats.rst

@@ -21,49 +21,38 @@ Install the library from `pip`_, like so::
 
     $ pip install python-mpd
 
+Add the ``mpdstats`` plugin to your configuration (see :ref:`using-plugins`).
+
 .. _pip: http://www.pip-installer.org/
 
-Configuring
------------
-
-To use it, enable it in your ``config.yaml`` by putting ``mpdstats`` on your
-``plugins`` line. Then, you'll probably want to configure the specifics of
-your MPD server. You can do that using an ``mpd:`` section in your
-``config.yaml``, which looks like this::
-
-    mpd:
-        host: localhost
-        port: 6600
-        password: seekrit
-
-If your MPD library is at another location then the beets library (e.g.,
-because one is mounted on a NFS share), you can specify the
-``music_directory`` in the config like this::
-
-    mpdstats:
-        music_directory: /PATH/TO/YOUR/FILES
-
-If you don't want the plugin to update the rating, you can disable it with::
-
-    mpdstats:
-        rating: False
-
-If you want to change the way the rating is calculated, you can set the
-``rating_mix`` option like this::
-
-    mpdstats:
-        rating_mix: 1.0
-
-For details, see below.
-
-
 Usage
 -----
 
-Now use the ``mpdstats`` command to fire it up::
+Use the ``mpdstats`` command to fire it up::
 
     $ beet mpdstats
 
+Configuration
+-------------
+
+Available options :
+
+- ``host``: mpd server name.
+  Default: ``localhost``.
+- ``music_directory``: if your MPD library is at another location than the
+  beets library (e.g., because one is mounted on a NFS share), specify the path
+  here.
+  By default it uses beets library directory.
+- ``password``: mpd server password.
+  Default: ``u''``
+- ``port``: mpd server port.
+  Default: ``6600``.
+- ``rating``: set it to ``no`` if you don't want the plugin to update the
+  rating.
+  Default: ``yes``
+- ``rating_mix``: change it to tune the way rating is calculated. See below for
+  details.
+  Default: ``0.75``
 
 A Word on Ratings
 -----------------

docs/plugins/mpdupdate.rst

@@ -6,9 +6,9 @@ update `MPD`_'s index whenever you change your beets library.
 
 .. _MPD: http://www.musicpd.org/
 
-To use it, enable it in your ``config.yaml`` by putting ``mpdupdate`` on your
-``plugins`` line. Then, you'll probably want to configure the specifics of your
-MPD server. You can do that using an ``mpd:`` section in your ``config.yaml``,
+To use it, enable it in your configuration (see :ref:`using-plugins`).
+Then, you'll probably want to configure the specifics of your MPD server.
+You can do that using an ``mpd:`` section in your ``config.yaml``,
 which looks like this::
 
     mpd:
@@ -22,3 +22,15 @@ If you want to communicate with MPD over a Unix domain socket instead over
 TCP, just give the path to the socket in the filesystem for the ``host``
 setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain
 socket.)
+
+Configuration
+-------------
+
+Available options :
+
+- ``host``: mpd server name.
+  Default: ``localhost``.
+- ``password``: mpd server password.
+  Default: ``u''``
+- ``port``: mpd server port.
+  Default: ``6600``.

docs/plugins/play.rst

@@ -4,6 +4,9 @@ Play Plugin
 The ``play`` plugin allows you to pass the results of a query to a music
 player in the form of an m3u playlist.
 
+Usage
+-----
+
 To use the plugin, enable it in your configuration (see
 :ref:`using-plugins`). Then use it by invoking the ``beet play`` command with
 a query. The command will create a temporary m3u file and open it using an
@@ -23,15 +26,19 @@ would on the command-line)::
     play:
         command: /usr/bin/command --option1 --option2 some_other_option
 
-You can configure the plugin to emit relative paths. Use the ``relative_to``
-configuration option::
-
-	play:
-		relative_to: /my/music/folder
-
-When using the ``-a`` option, the m3u will have the paths to each track on
-the matched albums. If you wish to have folders instead, you can change that
-by setting ``use_files: False`` in your configuration file.
-
 Enable beets' verbose logging to see the command's output if you need to
 debug.
+
+Configuration
+-------------
+
+- ``command``: command used to open the playlist.
+  Default: ``open`` on OS X, ``xdg-open`` on other Unixes and ``start`` on
+  Windows.
+- ``relative_to``: set that option if you want to emit relative paths by giving
+  the refefence folder (eg '/my/music/folder')
+  Default: ``None``
+- ``use_folders``: when using the ``-a`` option, the m3u will have the paths to
+  each track on the matched albums. Set it to ``yes`` to store paths to folders
+  instead.
+  Default: ``no``

docs/plugins/random.rst

@@ -5,8 +5,8 @@ The ``random`` plugin provides a command that randomly selects tracks or albums
 from your library. This can be helpful if you need some help deciding what to
 listen to.
 
-First, enable the plugin named ``random`` (see :doc:`/plugins/index`). You'll then
-be able to use the ``beet random`` command::
+First, enable the plugin named ``random`` (see :ref:`using-plugins`). You'll
+then be able to use the ``beet random`` command::
 
     $ beet random
     Aesop Rock - None Shall Pass - The Harbor Is Yours

docs/plugins/replaygain.rst

@@ -65,31 +65,35 @@ you can configure the path explicitly like so::
 Configuration
 -------------
 
-Available configuration options for the ``replaygain`` section in your
-configuration file include:
+Available options :
 
-* **overwrite**: By default, files that already have ReplayGain tags will not
-  be re-analyzed. If you want to analyze *every* file on import, you can set
-  the ``overwrite`` option for the plugin in your :doc:`configuration file
-  </reference/config>`, like so::
 
-      replaygain:
-          overwrite: yes
+- ``auto``: set it to ``no`` to disable replaygain analysis during import.
+  Default: ``yes``.
+- ``backend``: which backend to use for ReplayGain analysis.
+  Must be one of ``gstreamer`` or ``command``.
+  Default: ``command``
+- ``overwrite``: by default, files that already have ReplayGain tags will not
+  be re-analyzed. Set to ``yes`` if you want to analyze *every* file on import.
+  Default: ``no``.
+- ``targetlevel``: specify a number of decibels for the target loudness level
+  Default: ``89``
 
-* **targetlevel**: The target loudness level can be modified to any number of
-  decibels with the ``targetlevel`` option (default: 89 dB).
+  These options only work with the "command" backend:
 
-These options only work with the "command" backend:
-
-* **apply**: If you use a player that does not support ReplayGain
+- ``apply``: if you use a player that does not support ReplayGain
   specifications, you can force the volume normalization by applying the gain
   to the file via the ``apply`` option. This is a lossless and reversible
   operation with no transcoding involved.
-* **noclip**: The use of ReplayGain can cause clipping if the average volume
+- ``command``: use it to explicitely enter path to ``mp3gain`` or ``aacgain``
+  executable, if beets cannot find it by itself.
+  For example: '/Applications/MacMP3Gain.app/Contents/Resources/aacgain'
+  Default: ``u''``
+- ``noclip``: the use of ReplayGain can cause clipping if the average volume
   of a song is below the target level. By default, a "prevent clipping" option
   named ``noclip`` is enabled to reduce the amount of ReplayGain adjustment to
   whatever amount would keep clipping from occurring.
-
+  Default: ``yes``.
 
 Manual Analysis
 ---------------

docs/plugins/rewrite.rst

@@ -6,12 +6,11 @@ path formats. Specifically, it is intended to let you *canonicalize* names
 such as artists: for example, perhaps you want albums from The Jimi Hendrix
 Experience to be sorted into the same folder as solo Hendrix albums.
 
-To use field rewriting, first enable the plugin by putting ``rewrite`` on your
-``plugins`` line. Then, make a ``rewrite:`` section in your config file to
-contain your rewrite rules. Each rule consists of a field name, a regular
-expression pattern, and a replacement value. Rules are written ``fieldname
-regex: replacement``. For example, this line implements the Jimi Hendrix
-example above::
+To use field rewriting, first enable the plugin (see :ref:`using-plugins`).
+Then, make a ``rewrite:`` section in your config file to contain your rewrite
+rules. Each rule consists of a field name, a regular expression pattern, and a
+replacement value. Rules are written ``fieldname regex: replacement``.
+For example, this line implements the Jimi Hendrix example above::
 
     rewrite:
         artist The Jimi Hendrix Experience: Jimi Hendrix

docs/plugins/scrub.rst

@@ -11,7 +11,7 @@ Automatic Scrubbing
 -------------------
 
 To automatically remove files' tags before writing new ones, just
-enable the plugin (see :doc:`/plugins/index`). When importing new files (with
+enable the plugin (see :ref:`using-plugins`). When importing new files (with
 ``import.write`` turned on) or modifying files' tags with the ``beet modify``
 command, beets will first strip all types of tags entirely and then write the
 database-tracked metadata to the file.
@@ -31,11 +31,10 @@ The ``-W`` (or ``--nowrite``) option causes the command to just remove tags but
 not restore any information. This will leave the files with no metadata
 whatsoever.
 
-Configuring
------------
+Configuration
+-------------
 
-The plugin has one configuration option, ``auto``, which lets you disable
-automatic metadata stripping. To do so, add this to your ``config.yaml``::
+Available option :
 
-    scrub:
-        auto: no
+- ``auto``: set it to ``no`` to disable metadata stripping during import.
+  Default: ``yes``.

docs/plugins/smartplaylist.rst

@@ -7,9 +7,8 @@ created to work well with `MPD's`_ playlist functionality.
 
 .. _MPD's: http://www.musicpd.org/
 
-To use it, enable the plugin by putting ``smartplaylist`` in the ``plugins``
-section in your ``config.yaml``. Then configure your smart playlists like the
-following example::
+To use it, enable the plugin in your configuration (see :ref:`using-plugins`).
+Then configure your smart playlists like the following example::
 
     smartplaylist:
         relative_to: ~/Music
@@ -21,12 +20,6 @@ following example::
             - name: beatles.m3u
               query: 'artist:Beatles'
 
-If you intend to use this plugin to generate playlists for MPD, you should set
-``relative_to`` to your MPD music directory (by default, ``relative_to`` is
-``None``, and the absolute paths to your music files will be generated).
-
-``playlist_dir`` is where the generated playlist files will be put.
-
 You can generate as many playlists as you want by adding them to the
 ``playlists`` section, using beets query syntax (see
 :doc:`/reference/query`) for ``query`` and the file name to be generated for
@@ -60,8 +53,7 @@ to albums that have a ``for_travel`` extensible field set to 1::
       query: 'for_travel:1'
 
 By default, all playlists are automatically regenerated after every beets
-command that changes the library database. This can be disabled by specifying
-``auto: no``. To force regeneration, you can invoke it manually from the
+command that changes the library database. To force regeneration, you can invoke it manually from the
 command line::
 
     $ beet splupdate
@@ -72,3 +64,18 @@ You can also use this plugin together with the :doc:`mpdupdate`, in order to
 automatically notify MPD of the playlist change, by adding ``mpdupdate`` to
 the ``plugins`` line in your config file *after* the ``smartplaylist``
 plugin.
+
+Configuration
+-------------
+
+Available options :
+
+- ``auto``: set it to ``no`` to tell beets to stop regenerate the playlist
+  after every database change.
+  Default: ``yes``
+- ``playlist_dir``: where the generated playlist files will be put.
+  Default: ``u'.'``
+- ``relative_to``: if you intend to use this plugin to generate playlists for
+  MPD, make it points to your MPD music directory.
+  Default: ``None``, which means that absolute paths to your music files will
+  be generated.

docs/plugins/spotify.rst

@@ -37,27 +37,40 @@ Command-line options include:
 * ``--show-failures`` or ``-f``: List the tracks that did not match a Spotify
   ID.
 
-Configuring
------------
+Configuration
+-------------
 
 The default options should work as-is, but there are some options you can put in config.yaml:
 
-* ``mode``: See the section below on modes.
-* ``region_filter``: Use the 2-character country abbreviation to limit results
+* ``mode``: one of the following :
+
+      - "list": the default mode is to print out the playlist as a list of links.
+        This list can then be pasted in to a new or existing Spotify playlist.
+      - "open": This mode actually sends a link to your default browser with
+        instructions to open Spotify with the playlist you created.  Until this
+        has been tested on all platforms, it will remain optional.
+
+  Default: ``list``.
+* ``region_filter``: use the 2-character country abbreviation to limit results
   to that market.
-* ``show_failures``: Show the artist/album/track for each lookup that does not
+  Default: ``None``
+* ``show_failures``: qhow the artist/album/track for each lookup that does not
   return a Spotify ID (and therefore cannot be added to a playlist).
-* ``tiebreak``: How to choose the track if there is more than one identical
+  Default: ``no``
+* ``tiebreak``: how to choose the track if there is more than one identical
   result.  For example, there might be multiple releases of the same album.
   Currently, this defaults to "popularity", "first" simply chooses the first
   in the list returned by Spotify.
-* ``regex``: An array of regex transformations to perform on the
+  Default: ``popularity``
+* ``regex``: an array of regex transformations to perform on the
   track/album/artist fields before sending them to Spotify.  Can be useful for
   changing certain abbreviations, like ft. -> feat.  See the examples below.
-* ``artist_field`` / ``album_field`` / ``track_field``: These allow the user
+  Default: ``[]``
+* ``artist_field`` / ``album_field`` / ``track_field``: these allow the user
   to choose a different field to send to Spotify when looking up the track,
   album and artist.  Most users will not want to change this.
 
+
 Example Configuration
 ---------------------
 
@@ -96,12 +109,3 @@ Example Configuration
             }
         ]
 
-Spotify Plugin Modes
----------------------
-
-* ``list``: The default mode is to print out the playlist as a list of links.
-  This list can then be pasted in to a new or existing Spotify playlist.
-* ``open``: This mode actually sends a link to your default browser with
-  instructions to open Spotify with the playlist you created.  Until this has
-  been tested on all platforms, it will remain optional.
-

docs/plugins/the.rst

@@ -2,39 +2,41 @@ The Plugin
 ==========
 
 The ``the`` plugin allows you to move patterns in path formats. It's suitable,
-for example, for moving articles from string start to the end. This is useful 
-for quick search on filesystems and generally looks good. Plugin DOES NOT 
-change tags. By default plugin supports English "the, a, an", but custom 
+for example, for moving articles from string start to the end. This is useful
+for quick search on filesystems and generally looks good. Plugin DOES NOT
+change tags. By default plugin supports English "the, a, an", but custom
 regexp patterns can be added by user. How it works::
 
     The Something -> Something, The
     A Band -> Band, A
     An Orchestra -> Orchestra, An
 
-To use plugin, enable it by including ``the`` into ``plugins`` line of your
-beets config. The plugin provides a template function called ``%the`` for use
-in path format expressions::
+Enable the plugin (see :doc:`/plugins/index`) and then make use of a template
+function called ``%the`` for use in path format expressions::
 
     paths:
         default: %the{$albumartist}/($year) $album/$track $title
 
 The default configuration moves all English articles to the end of the string,
-but you can override these defaults to make more complex changes::
+but you can override these defaults to make more complex changes.
 
-    the:
-        # handle "The" (on by default)
-        the: yes
-        # handle "A/An" (on by default)
-        a: yes
-        # format string, {0} - part w/o article, {1} - article
-        # spaces already trimmed from ends of both parts
-        # default is '{0}, {1}'
-        format: '{0}, {1}'
-        # strip instead of moving to the end, default is off
-        strip: no
-        # custom regexp patterns, space-separated
-        patterns: ...
+Configuration
+-------------
+
+Available options:
+
+- ``a``: handle "A/An" moves
+  Default: ``yes``
+- ``format``: format string with *{0}: part w/o article* and *{1} - article*.
+  Spaces are already trimmed from ends of both parts.
+  Default: ``u'{0}, {1}'``
+- ``strip``:
+  Default: ``no``
+- ``patterns``: custom regexp patterns, space-separated. Custom patterns are
+  case-insensitive regular expressions. Patterns can be matched anywhere in the
+  string (not just the beginning), so use ``^`` if you intend to match leading
+  words.
+  Default: ``[]``
+- ``the``: handle "The" moves
+  Default: ``yes``
 
-Custom patterns are case-insensitive regular expressions. Patterns can be
-matched anywhere in the string (not just the beginning), so use ``^`` if you
-intend to match leading words.

docs/plugins/web.rst

@@ -20,8 +20,7 @@ flask``.
 
 .. _Flask: http://flask.pocoo.org/
 
-Put ``web`` on your ``plugins`` line in your configuration file to enable the
-plugin.
+Finally, enable the plugin in your configuration (see :ref:`using-plugins`).
 
 Run the Server
 --------------
@@ -50,6 +49,16 @@ Type queries into the little search box. Double-click a track to play it with
 
 .. _HTML5 Audio: http://www.w3.org/TR/html-markup/audio.html
 
+Configuration
+-------------
+
+Available options :
+
+- ``host``: server hostname
+  Default: ``u''``
+- ``port``: server port
+  Default: `8337`
+
 Implementation
 --------------
 

docs/plugins/zero.rst

@@ -4,14 +4,18 @@ Zero Plugin
 The ``zero`` plugin allows you to null fields in files' metadata tags. Fields
 can be nulled unconditionally or conditioned on a pattern match. For example,
 the plugin can strip useless comments like "ripped by MyGreatRipper." This
-plugin only affects files' tags; the beets database is unchanged.
+plugin only affects files' tags ; the beets database is left unchanged.
 
-To use the plugin, enable it by including ``zero`` in the ``plugins`` line of
-your configuration file. To configure the plugin, use a ``zero:`` section in
-your configuration file. Set ``fields`` to the (whitespace-separated) list of
-fields to change. You can get the list of available fields by running ``beet
-fields``.  To conditionally filter a field, use ``field: [regexp, regexp]`` to
-specify regular expressions.
+To use the plugin, enable the plugin in your configuration (see :ref:`using-plugins`).
+
+Configuration
+-------------
+
+Available option :
+
+- ``fields``: whitespace-separated list of fields to change. You can get the
+  list of available fields by running ``beet fields``.  To conditionally filter
+  a field, use ``field: [regexp, regexp]`` to specify regular expressions.
 
 For example::