Merge lp:~allenap/commandant/readme-to-rest into lp:commandant

[Gavin Panella]

Ensure README is valid reST, and renders without warnings.

Fix README so that it's valid reST. I've already uploaded the README in the branch by hand to PyPI and confirmed it works okay there (see http://pypi.python.org/pypi/commandant).

[Jamu Kakar (jkakar)]

This is great, thanks!

review: Approve

=== modified file 'README'
--- README	2010-06-12 13:56:44 +0000
+++ README	2012-06-12 17:11:25 +0000
@@ -27,18 +27,18 @@
 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 On Ubuntu systems, the complete text of the GNU General Public
-Version 2 License is in `/usr/share/common-licenses/GPL-2'.
+Version 2 License is in ``/usr/share/common-licenses/GPL-2``.
 
 
 Using Commandant
 ================
 
-Commandant can be used as a command runner.  The bin/commandant
-program can present an application made up of commands and help
-topics grouped together in a directory.  The 'example' program
-described in the following sections is available in the
-extras/example directory.  You can try it out from the current
-directory by running the following commands.
+Commandant can be used as a command runner.  The ``bin/commandant``
+program can present an application made up of commands and help topics
+grouped together in a directory.  The ``example`` program described in
+the following sections is available in the ``example`` directory.  You
+can try it out from the current directory by running the following
+commands::
 
   $ alias example="bin/commandant example"
   $ source example/tab-completion.sh
@@ -48,12 +48,12 @@
 ---------------------------
 
 Commands are grouped into Commandant programs.  A Commandant program
-is made up of an arbitrary number of commands stored in a directory.
+is made up of an arbitrary number of commands stored in a directory::
 
   $ mkdir -p ~/example
 
 An alias can be used to provide a name that can used to run commands
-in the Commandant program.
+in the Commandant program::
 
   $ alias example="commandant ~/example"
 
@@ -61,8 +61,8 @@
 Getting help
 ------------
 
-Commands provides builtin 'help' and 'version' commands.  Running
-the example program by itself shows basic help information.
+Commands provides builtin ``help`` and ``version`` commands.  Running
+the example program by itself shows basic help information::
 
   $ example
   Commandant -- a framework for building command-oriented tools
@@ -72,21 +72,21 @@
     commandant help commands  List all commands
     commandant help topics    List all help topics
 
-Passing the 'commands' topic to the 'help' command lists the
-commands that are available, with a short summary about each one.
+Passing the ``commands`` topic to the ``help`` command lists the
+commands that are available, with a short summary about each one::
 
   $ example help commands
   help    Show help about a command or topic.
   version Show version of commandant.
 
-Passing the 'topics' topic to the 'help' command lists the help
-topics that are available, with a short summary about each one.
+Passing the ``topics`` topic to the ``help`` command lists the help
+topics that are available, with a short summary about each one::
 
   $ example help topics
   commands   Basic help for all commands.
   topics     Topics list.
 
-The 'version' command shows the version of Commandant being used.
+The ``version`` command shows the version of Commandant being used::
 
   $ example version
   commandant 0.1
@@ -96,13 +96,13 @@
 ----------------------------
 
 One of the easiest ways to add a command to a Commandant program is
-by creating a shell script and making it executable.
+by creating a shell script and making it executable::
 
   $ echo -e '#!/bin/sh\necho Hello, world!' > ~/example/hello
   $ chmod +x ~/example/hello
 
-The new 'hello' command in the 'example' program is now registered
-and ready to use.
+The new ``hello`` command in the ``example`` program is now registered
+and ready to use::
 
   $ example help commands
   hello
@@ -110,7 +110,7 @@
   version Show version of commandant.
 
 You should see 'Hello, world!' printed to your screen when you run
-it.
+it::
 
   $ example hello
   Hello, world!
@@ -120,13 +120,13 @@
 -------------------------------------------------
 
 Commandant will pass all arguments beyond the command name to the
-executable for that command.
+executable for that command::
 
   $ echo -e '#!/bin/sh\necho $*' > ~/example/echo
   $ chmod +x ~/example/echo
 
 Again, just by putting an executable file in the command directory,
-the new 'echo' command has been added to the 'example' program.
+the new ``echo`` command has been added to the ``example`` program::
 
   $ example help commands
   echo
@@ -134,7 +134,7 @@
   help    Show help about a command or topic.
   version Show version of commandant.
 
-The new 'echo' command will repeat whatever we tell it.
+The new ``echo`` command will repeat whatever we tell it::
 
   $ example echo Hello there!
   Hello there!
@@ -143,12 +143,12 @@
 Providing help for commands
 ---------------------------
 
-The commands in the 'example' program have been very easy to add,
+The commands in the ``example`` program have been very easy to add,
 but they could be easier to use.  Commandant's builtin help system
 can be extended to provide help topics for user-provided commands.
 Files in the command directory with a .txt extension, and with the
 same name as a command, will be treated as help content for that
-command.  Adding help content for the 'hello' command is quite easy.
+command.  Adding help content for the ``hello`` command is quite easy::
 
   $ cat ~/example/hello.txt
   Greet the world!
@@ -156,7 +156,7 @@
   Print 'Hello, world!' to the screen.
 
 The first line in a help topic is used as a short description.  This
-short description is used when listing commands.
+short description is used when listing commands::
 
   $ example help commands
   echo
@@ -164,9 +164,9 @@
   help     Show help about a command or topic.
   version  Show version of commandant.
 
-Notice that the 'hello' command uses the short description from the
+Notice that the ``hello`` command uses the short description from the
 help topic.  The complete help text can be seen by passing the
-command name to the 'help' command.
+command name to the ``help`` command::
 
   $ example help hello
   Print 'Hello, world!' to the screen.
@@ -175,9 +175,9 @@
 Providing a custom splash page
 ------------------------------
 
-The stock help text shown when the 'help' command is run points
+The stock help text shown when the ``help`` command is run points
 users to the list of commands and help topics.  It can be overridden
-by providing a file called basic.txt.
+by providing a file called basic.txt::
 
   $ cat ~/example/basic.txt
   example -- A collection of command examples that work with Commandant.
@@ -187,8 +187,8 @@
     example help commands  List all commands
     example help topics    List all help topics
 
-The contents of this file are shown when the 'help' command is run
-without a topic.
+The contents of this file are shown when the ``help`` command is run
+without a topic::
 
   $ example help
   example -- A collection of command examples that work with Commandant.
@@ -206,7 +206,7 @@
 topics, not bound to any command name.  Files in the command
 directory with a .txt extension, and with a name that doesn't match
 any command name, will be treated as help topics.  Adding help to
-describe a concept, for example, is quite easy.
+describe a concept, for example, is quite easy::
 
   $ cat ~/example/greetings.txt
   Greetings are a way to initiate communication.
@@ -221,15 +221,15 @@
 
 As with help files for commands, the first line contains a short
 summary with help text following.  The topic will now appear in the
-topics list.
+topics list::
 
   $ example help topics
   commands   Basic help for all commands.
   greetings  Greetings are a way to initiate communication.
   topics     Topics list.
 
-The help text can be seen by passing the topic name to the 'help'
-command.
+The help text can be seen by passing the topic name to the ``help``
+command::
 
   $ example help greetings
   Greeting (also called accosting) is a way for human beings (as well
@@ -252,7 +252,7 @@
 Commandant loads commands from the command directory it imports
 Python commands from files with a .py extension.  The commands in
 the files need to subclass the Command class and need to be named
-using the cmd_<name> naming convention.
+using the cmd_<name> naming convention::
 
   $ cat example/rock-fact.py
   from bzrlib.commands import Command
@@ -266,9 +266,9 @@
           print >>self.outf, "Rocks are really hard."
 
 Just like with executable commands, adding a Python command is as
-easy as adding a file to the command directory.  An 'outf' attribute
+easy as adding a file to the command directory.  An ``outf`` attribute
 will be set on the command object when it's run and should be used
-when printing text.
+when printing text::
 
   $ example help commands
   echo
@@ -278,10 +278,10 @@
   version    Show version of commandant.
 
 The new command is available using the name of the class, without
-the 'cmd_' part, and with underscores converted to dashes.  The
+the ``cmd_`` part, and with underscores converted to dashes.  The
 doctring is used to provide builtin help.  The first line is used as
 the summary and the subsequent content is used as the help text,
-just like in help files for executable commands.
+just like in help files for executable commands::
 
   $ example help rock-fact
   This command prints a fascinating fact about rocks.
@@ -296,7 +296,7 @@
 One of the main advantages of writing Python commands is being able
 to express command-line argument and option parameters.  bzrlib uses
 this data to automatically provide parsing and integration with the
-help system.
+help system::
 
   $ cat example/fortune.py
   from random import randint
@@ -335,7 +335,7 @@
 Commandant has builtin support for writing commands that need to run
 in a Twisted reactor.  Simply subclass TwistedCommand and implement
 a command as you normally would.  It's run() method will be called
-inside a running reactor.
+inside a running reactor::
 
   $ cat example/get-page.py
   from twisted.internet import reactor
@@ -390,7 +390,7 @@
 
 The first step is to create an entry point which registers commands
 and help topics and then subsequently runs your program.  The
-CommandController is both a registry and dispatching device:
+CommandController is both a registry and dispatching device::
 
   from commandant import builtins
   from commandant.controller import CommandController
@@ -413,9 +413,9 @@
       controller.run(argv[1:])
 
 The name, version, summary and URL are used in generated help text.
-The 'builtins' module contains the builtin 'help' and 'version'
-commands, and the 'basic', 'commands', 'hidden-commands' and
-'topics' help topics.
+The ``builtins`` module contains the builtin ``help`` and ``version``
+commands, and the ``basic``, ``commands``, ``hidden-commands`` and
+``topics`` help topics.
 
 
 Registering application commands
@@ -423,10 +423,10 @@
 
 Commands can be grouped in a module and registered with the command
 controller.  Just like in the examples above, command classes should
-be named using the 'cmd_command_name' naming convention and will be
+be named using the ``cmd_command_name`` naming convention and will be
 loaded automatically when the module is registered.  If all the
 commands in the examples above were grouped in an example.commands
-module they could be registered just like the builtin commands:
+module they could be registered just like the builtin commands::
 
   from example import commands
 
@@ -438,7 +438,7 @@
 
 In the examples above, help topics are text files in a directory.
 When embedding Commandant in an application, its easier to use
-Python for help topics:
+Python for help topics::
 
   from commandant.help_topics import DocstringHelpTopic
 
@@ -456,7 +456,7 @@
 
 Registering help topics is just like registering commands.  They can
 be grouped in a module and registered with the command controller.
-Topics should use the 'topic_document_name' naming convention.
+Topics should use the ``topic_document_name`` naming convention::
 
   from example import help_topics
 
@@ -466,7 +466,7 @@
 Providing a custom splash page
 ------------------------------
 
-The stock help text shown when the 'help' command is run points
+The stock help text shown when the ``help`` command is run points
 users to the list of commands and help topics that have been
-registered with the controller.  If a 'topic_basic' help topic has
+registered with the controller.  If a ``topic_basic`` help topic has
 been registered it will be shown instead of the builtin splash page.