changelog & doc tweaks for smartplaylist (#80)

beetsplug/smartplaylist.py

@@ -19,6 +19,7 @@ from __future__ import print_function
 from beets.plugins import BeetsPlugin
 from beets import config, ui
 from beets.util import normpath, syspath
+from beets.util.functemplate import Template
 import os
 
 # Global variables so that smartplaylist can detect database changes and run
@@ -28,10 +29,9 @@ library = None
 
 
 def update_playlists(lib):
-    from beets.util.functemplate import Template
-    print("Updating smart playlists...")
+    ui.print_("Updating smart playlists...")
     playlists = config['smartplaylist']['playlists'].get(list)
-    playlist_dir = config['smartplaylist']['playlist_dir'].get(unicode)
+    playlist_dir = config['smartplaylist']['playlist_dir'].as_filename()
     relative_to = config['smartplaylist']['relative_to'].get()
     if relative_to:
         relative_to = normpath(relative_to)
@@ -56,7 +56,7 @@ def update_playlists(lib):
             with open(syspath(m3u_path), 'w') as f:
                 for path in m3us[m3u]:
                     f.write(path + '\n')
-    print("... Done")
+    ui.print_("... Done")
 
 
 class SmartPlaylistPlugin(BeetsPlugin):

docs/changelog.rst

@@ -14,18 +14,21 @@ New configuration options:
 Other new stuff:
 
 * Support for Windows Media/ASF audio files. Thanks to Dave Hayes.
-* Two new plugin events were added: *database_change* and *cli_exit*. Thanks to
-  Dang Mai Hai.
+* New :doc:`/plugins/smartplaylist`: generate and maintain m3u playlist files
+  based on beets queries. Thanks to Dang Mai Hai.
+* Two new plugin events were added: *database_change* and *cli_exit*. Thanks
+  again to Dang Mai Hai.
 * Track titles in the importer's difference display are now broken across two
   lines for readability. Thanks to mrmachine.
 * Some changes to the way candidates are recommended for selection, thanks to
   mrmachine:
-    * Partial album matches are never "strong" recommendations.
-    * When a match isn't great but is either better than all the others or the
-      only match, it is given a "low" (rather than "medium") recommendation.
-    * There is no prompt default (i.e., input is required) when matches are
-      bad: "low" or "none" recommendations or when choosing a candidate
-      other than the first.
+
+  * Partial album matches are never "strong" recommendations.
+  * When a match isn't great but is either better than all the others or the
+    only match, it is given a "low" (rather than "medium") recommendation.
+  * There is no prompt default (i.e., input is required) when matches are
+    bad: "low" or "none" recommendations or when choosing a candidate
+    other than the first.
 
 1.1b1 (January 29, 2013)
 ------------------------

docs/plugins/smartplaylist.rst

@@ -3,9 +3,9 @@ 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.
+created to work well with `MPD's`_ playlist functionality.
 
-.. _MPD: http://mpd.wikia.com/wiki/Music_Player_Daemon_Wiki
+.. _MPD's: 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
@@ -28,24 +28,24 @@ If you intend to use this plugin to generate playlists for MPD, you should set
 ``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
+``playlists`` section, using beets query syntax (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).
+``name``. If you have existing files with the same names, you should
+back them up---they will be overwritten when the plugin runs.
 
-For more advanced usage, you can also specify metadata (see
-:doc:`/reference/pathformat/`) in the ``name`` field, for example::
+For more advanced usage, you can use template syntax (see
+:doc:`/reference/pathformat/`) in the ``name`` field. For example::
 
     - query: 'year::201(0|1)'
       name: 'ReleasedIn$year.m3u'
 
-This will query all the songs in 2010 and 2011, and generate the 2 playlist
+This will query all the songs in 2010 and 2011 and generate the two playlist
 files `ReleasedIn2010.m3u` and `ReleasedIn2011.m3u` using those songs.
 
-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::
+By default, all playlists are regenerated after every beets command that
+changes the library database. To force regeneration, you can invoke it manually
+from the command line::
 
     $ beet splupdate
 
-which will generate your new smart playlists.
+which will generate your new smart playlists.

docs/reference/config.rst

@@ -250,6 +250,8 @@ Either ``skip`` (default) or ``asis``, specifying what should happen in
 quiet mode (see the ``-q`` flag to ``import``, above) when there is no
 strong recommendation.
 
+.. _none_rec_action:
+
 none_rec_action
 ~~~~~~~~~~~~~~~