From 7e6cdd75d6d96d5585452af0b04904b150707dcb Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Fri, 23 Mar 2012 10:26:50 -0700
Subject: [PATCH] docs & changelog for rdm plugin

---
 beetsplug/rdm.py       | 24 +++++++++++++++++-------
 docs/changelog.rst     |  1 +
 docs/plugins/index.rst |  1 +
 docs/plugins/rdm.rst   | 17 +++++++++++++++++
 4 files changed, 36 insertions(+), 7 deletions(-)
 create mode 100644 docs/plugins/rdm.rst

diff --git a/beetsplug/rdm.py b/beetsplug/rdm.py
index f7efa2bf3..8131cdf58 100644
--- a/beetsplug/rdm.py
+++ b/beetsplug/rdm.py
@@ -1,20 +1,30 @@
+# This file is part of beets.
+# Copyright 2011, Philippe Mongeau.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+# 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+
 from beets.plugins import BeetsPlugin
 from beets.ui import Subcommand, decargs, print_
 from beets.util.functemplate import Template
 import random
 
-
+"""Get a random song or album from the library.
 """
-Get a random song or album from the library
-"""
-
 
 def random_item(lib, config, opts, args):
     query = decargs(args)
     path = opts.path
     fmt = opts.format
 
-
     if fmt is None:
         # If no specific template is supplied, use a default
         if opts.album:
@@ -23,7 +33,6 @@ def random_item(lib, config, opts, args):
             fmt = u'$artist - $album - $title'
     template = Template(fmt)
 
-
     if opts.album:
         items = list(lib.albums(query))
         item = random.choice(items)
@@ -39,7 +48,8 @@ def random_item(lib, config, opts, args):
         else:
             print_(template.substitute(item.record))
 
-random_cmd = Subcommand('random', help='chose a random track, album, artist, etc.')
+random_cmd = Subcommand('random',
+                        help='chose a random track or album')
 random_cmd.parser.add_option('-a', '--album', action='store_true',
         help='choose an album instead of track')
 random_cmd.parser.add_option('-p', '--path', action='store_true',
diff --git a/docs/changelog.rst b/docs/changelog.rst
index bb2049177..708fccbcc 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -10,6 +10,7 @@ Changelog
   choices: skip the new music (the previous behavior), keep both, or remove the
   old music. See the :ref:`guide-duplicates` section in the autotagging guide
   for details.
+* New :doc:`/plugins/rdm`: Randomly select albums and tracks from your library.
 * New :doc:`/plugins/m3uupdate`: Catalog imported files in an ``m3u`` playlist
   file for easy importing to other systems. Thanks to Fabrice Laporte.
 * :doc:`/plugins/bpd`: Use Gstreamer's ``playbin2`` element instead of the
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index f0736b177..990197b58 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -81,6 +81,7 @@ Miscellaneous
 '''''''''''''
 
 * :doc:`web`: An experimental Web-based GUI for beets.
+* :doc:`rdm`: Randomly choose albums and tracks from your library.
 * :doc:`bpd`: A music player for your beets library that emulates `MPD`_ and is
   compatible with `MPD clients`_.
 
diff --git a/docs/plugins/rdm.rst b/docs/plugins/rdm.rst
new file mode 100644
index 000000000..1ced7fecf
--- /dev/null
+++ b/docs/plugins/rdm.rst
@@ -0,0 +1,17 @@
+Random Plugin
+=============
+
+The ``rdm`` 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 ``rdm`` (see :doc:`/plugins/index`). You'll then
+be able to use the ``beet random`` command::
+
+    $ beet random
+    Aesop Rock - None Shall Pass - The Harbor Is Yours
+
+The command has several options that resemble those for the ``beet list``
+command (see :doc:`/reference/cli`). To choose an album instead of a single
+track, use ``-a``; to print paths to items instead of metadata, use ``-p``; and
+to use a custom format for printing, use ``-f FORMAT``.