all plugins: auto-generate READMEs

Starting with this commit, there should be no "original" text
in READMEs.
Instead, the entire text should be in docstrings, and READMEs
should be automatically generated from these docstrings.

Motivation:

* The same help is available both via IRC and in the README
  (although the README can be more detailed, as only the first
  paragraph will be shown on IRC)
* This will allow auto-generating plugin help on docs.limnoria.net
  using the same content as the README, as it's sourced from the
  docstrings

Additionally, this converts all READMEs from Markdown to ReST,
because the documentation already uses ReST, and other docstrings
in the codebase are in ReST for this reason.

plugins/Admin/README.rst

@@ -0,0 +1,55 @@
+.. _plugin-Admin:
+
+Documentation for the Admin plugin for Supybot
+==============================================
+
+Purpose
+-------
+These are commands useful for administrating the bot; they all require their
+caller to have the 'admin' capability.  This plugin is loaded by default.
+
+Usage
+-----
+This plugin provides access to administrative commands, such as
+adding capabilities, managing ignore lists, and joining channels.
+This is a core Supybot plugin that should not be removed!
+
+Commands
+--------
+acmd <command> [<arg> ...]
+  Perform <command> (with associated <arg>s on all channels on current network.
+
+capability add <name|hostmask> <capability>
+  Gives the user specified by <name> (or the user to whom <hostmask> currently maps) the specified capability <capability>
+
+capability remove <name|hostmask> <capability>
+  Takes from the user specified by <name> (or the user to whom <hostmask> currently maps) the specified capability <capability>
+
+channels takes no arguments
+  Returns the channels the bot is on.
+
+clearq takes no arguments
+  Clears the current send queue for this network.
+
+ignore add <hostmask|nick> [<expires>]
+  This will set a persistent ignore on <hostmask> or the hostmask currently associated with <nick>. <expires> is an optional argument specifying when (in "seconds from now") the ignore will expire; if it isn't given, the ignore will never automatically expire.
+
+ignore list takes no arguments
+  Lists the hostmasks that the bot is ignoring.
+
+ignore remove <hostmask|nick>
+  This will remove the persistent ignore on <hostmask> or the hostmask currently associated with <nick>.
+
+join <channel> [<key>]
+  Tell the bot to join the given channel. If <key> is given, it is used when attempting to join the channel.
+
+nick [<nick>] [<network>]
+  Changes the bot's nick to <nick>. If no nick is given, returns the bot's current nick.
+
+Configuration
+-------------
+supybot.plugins.Admin.public
+  This config variable defaults to "True", is not network-specific, and is  not channel-specific.
+
+  Determines whether this plugin is publicly visible.
+

plugins/Aka/README.rst

@@ -0,0 +1,115 @@
+.. _plugin-Aka:
+
+Documentation for the Aka plugin for Supybot
+============================================
+
+Purpose
+-------
+This plugin allows the user to create various aliases (known as "Akas", since
+Alias is the name of another plugin Aka is based on) to other commands or
+combinations of other commands (via nested commands).
+
+Usage
+-----
+This plugin allows users to define aliases to commands and combinations
+of commands (via nesting).
+
+Importing from Alias
+^^^^^^^^^^^^^^^^^^^^
+
+Add an aka, Alias, which eases the transitioning to Aka from Alias.
+
+First we will load Alias and Aka::
+
+    <jamessan> @load Alias
+    <bot> jamessan: The operation succeeded.
+    <jamessan> @load Aka
+    <bot> jamessan: The operation succeeded.
+
+Then we import the Alias database to Aka in case it exists and unload
+Alias::
+
+    <jamessan> @importaliasdatabase
+    <bot> jamessan: The operation succeeded.
+    <jamessan> @unload Alias
+    <bot> jamessan: The operation succeeded.
+
+And now we will finally add the Aka ``alias`` itself::
+
+    <jamessan> @aka add "alias" "aka $1 $*"
+    <bot> jamessan: The operation succeeded.
+
+Now you can use Aka as you used Alias before.
+
+Trout
+^^^^^
+
+Add an aka, trout, which expects a word as an argument::
+
+    <jamessan> @aka add trout "reply action slaps $1 with a large trout"
+    <bot> jamessan: The operation succeeded.
+    <jamessan> @trout me
+    * bot slaps me with a large trout
+
+This ``trout`` aka requires the plugin ``Reply`` to be loaded since it
+provides the ``action`` command.
+
+LastFM
+^^^^^^
+
+Add an aka, ``lastfm``, which expects a last.fm username and replies with
+their most recently played item::
+
+    @aka add lastfm "rss [format concat http://ws.audioscrobbler.com/1.0/user/ [format concat [web urlquote $1] /recenttracks.rss]]"
+
+This ``lastfm`` aka requires the following plugins to be loaded: ``RSS``,
+``Format`` and ``Web``.
+
+``RSS`` provides ``rss``, ``Format`` provides ``concat`` and ``Web`` provides
+``urlquote``.
+
+Note that if the nested commands being aliased hadn't been quoted, then
+those commands would have been run immediately, and ``@lastfm`` would always
+reply with the same information, the result of those commands.
+
+Commands
+--------
+add [--channel <#channel>] <name> <command>
+  Defines an alias <name> that executes <command>. The <command> should be in the standard "command argument [nestedcommand argument]" arguments to the alias; they'll be filled with the first, second, etc. arguments. $1, $2, etc. can be used for required arguments. @1, @2, etc. can be used for optional arguments. $* simply means "all arguments that have not replaced $1, $2, etc.", ie. it will also include optional arguments.
+
+remove [--channel <#channel>] <name>
+  Removes the given alias, if unlocked.
+
+lock [--channel <#channel>] <alias>
+  Locks an alias so that no one else can change it.
+
+unlock [--channel <#channel>] <alias>
+  Unlocks an alias so that people can define new aliases over it.
+
+importaliasdatabase takes no arguments
+  Imports the Alias database into Aka's, and clean the former.
+
+show [--channel <#channel>] <alias>
+  This command shows the content of an Aka.
+
+list [--channel <#channel>] [--keys] [--unlocked|--locked]
+  Lists all Akas defined for <channel>. If <channel> is not specified, lists all global Akas. If --keys is given, lists only the Aka names and not their commands.
+
+set [--channel <#channel>] <name> <command>
+  Overwrites an existing alias <name> to execute <command> instead. The <command> should be in the standard "command argument [nestedcommand argument]" arguments to the alias; they'll be filled with the first, second, etc. arguments. $1, $2, etc. can be used for required arguments. @1, @2, etc. can be used for optional arguments. $* simply means "all arguments that have not replaced $1, $2, etc.", ie. it will also include optional arguments.
+
+search [--channel <#channel>] <query>
+  Searches Akas defined for <channel>. If <channel> is not specified, searches all global Akas.
+
+Configuration
+-------------
+supybot.plugins.Aka.maximumWordsInName
+  This config variable defaults to "5", is not network-specific, and is  not channel-specific.
+
+  The maximum number of words allowed in a command name. Setting this to an high value may slow down your bot on long commands.
+
+supybot.plugins.Aka.public
+  This config variable defaults to "True", is not network-specific, and is  not channel-specific.
+
+  Determines whether this plugin is publicly visible.
+

plugins/Aka/plugin.py

@@ -498,8 +498,68 @@ def doPost(self, handler, path, form, *args, **kwargs):
 
 
 class Aka(callbacks.Plugin):
-    """This plugin allows users to define aliases to commands and combinations
-    of commands (via nesting)."""
+    """
+    This plugin allows users to define aliases to commands and combinations
+    of commands (via nesting).
+
+    Importing from Alias
+    ^^^^^^^^^^^^^^^^^^^^
+
+    Add an aka, Alias, which eases the transitioning to Aka from Alias.
+
+    First we will load Alias and Aka::
+
+        <jamessan> @load Alias
+        <bot> jamessan: The operation succeeded.
+        <jamessan> @load Aka
+        <bot> jamessan: The operation succeeded.
+
+    Then we import the Alias database to Aka in case it exists and unload
+    Alias::
+
+        <jamessan> @importaliasdatabase
+        <bot> jamessan: The operation succeeded.
+        <jamessan> @unload Alias
+        <bot> jamessan: The operation succeeded.
+
+    And now we will finally add the Aka ``alias`` itself::
+
+        <jamessan> @aka add "alias" "aka $1 $*"
+        <bot> jamessan: The operation succeeded.
+
+    Now you can use Aka as you used Alias before.
+
+    Trout
+    ^^^^^
+
+    Add an aka, trout, which expects a word as an argument::
+
+        <jamessan> @aka add trout "reply action slaps $1 with a large trout"
+        <bot> jamessan: The operation succeeded.
+        <jamessan> @trout me
+        * bot slaps me with a large trout
+
+    This ``trout`` aka requires the plugin ``Reply`` to be loaded since it
+    provides the ``action`` command.
+
+    LastFM
+    ^^^^^^
+
+    Add an aka, ``lastfm``, which expects a last.fm username and replies with
+    their most recently played item::
+
+        @aka add lastfm "rss [format concat http://ws.audioscrobbler.com/1.0/user/ [format concat [web urlquote $1] /recenttracks.rss]]"
+
+    This ``lastfm`` aka requires the following plugins to be loaded: ``RSS``,
+    ``Format`` and ``Web``.
+
+    ``RSS`` provides ``rss``, ``Format`` provides ``concat`` and ``Web`` provides
+    ``urlquote``.
+
+    Note that if the nested commands being aliased hadn't been quoted, then
+    those commands would have been run immediately, and ``@lastfm`` would always
+    reply with the same information, the result of those commands.
+    """
 
     def __init__(self, irc):
         self.__parent = super(Aka, self)