From f4107703fb4d75adf9ec750d0b6e191cc7d0f695 Mon Sep 17 00:00:00 2001
From: Dang Mai <contact@dangmai.net>
Date: Wed, 30 Jan 2013 09:30:36 -0500
Subject: [PATCH] Add documentation for plugin

---
 docs/plugins/index.rst         |  2 ++
 docs/plugins/smartplaylist.rst | 42 ++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 docs/plugins/smartplaylist.rst

diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 898795150..2217f4d91 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -59,6 +59,7 @@ disabled by default, but you can turn them on as described above.
    ihate
    convert
    info
+   smartplaylist
 
 Autotagger Extensions
 ''''''''''''''''''''''
@@ -92,6 +93,7 @@ Interoperability
 * :doc:`mpdupdate`: Automatically notifies `MPD`_ whenever the beets library
   changes.
 * :doc:`importfeeds`: Keep track of imported files via ``.m3u`` playlist file(s) or symlinks.
+* :doc:`smartplaylist`: Generate smart playlists based on beets queries.
 
 Miscellaneous
 '''''''''''''
diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst
new file mode 100644
index 000000000..80b44df1d
--- /dev/null
+++ b/docs/plugins/smartplaylist.rst
@@ -0,0 +1,42 @@
+Smart Playlist Plugin
+=====================
+
+``smartplaylist`` is a plugin to generate smart playlists in m3u format based on
+beets queries every time your library changes. This plugin is specifically
+created to work well with `MPD`_'s playlist functionality.
+
+.. _MPD: http://mpd.wikia.com/wiki/Music_Player_Daemon_Wiki
+
+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::
+
+    smartplaylist:
+        relative_to: ~/Music
+        playlist_dir: ~/.mpd/playlists
+        playlists:
+            - query: ''
+              name: all.m3u
+
+            - query: 'artist:Beatles'
+              name: beatles.m3u
+
+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 the normal querying format (see
+:doc:`/reference/query`) for ``query`` and the file name to be generated for
+``name`` (*note*: if you have existing files with the same names, you should
+back them up, as they will be overwritten when the plugin runs).
+
+If you add a smart playlist to your ``config.yaml`` file and don't want to wait
+until the next time your library changes for ``smartplugin`` to run, you can
+invoke it manually from the command-line::
+
+    $ beet splupdate
+
+which will generate your new smart playlists.
\ No newline at end of file