Update docs for 0.2.0 release; Use rst changelog

CHANGELOG.rst

@@ -0,0 +1,29 @@
+Change Log
+==========
+
+All notable changes to pycommand will be documented here. The project
+adheres to `Semantic Versioning <http://semver.org/>`_.
+
+
+0.2.0 - 2015-05-21
+------------------
+
+Added
+#####
+- Full example of a command with subcommands
+- Create quick templates via pycommand script (``pycommand init``)
+- Unit tests and automatic testing via Travis-CI
+- Documentation ``man`` (.3) and ``info`` (.info) pages
+
+Changed
+#######
+- Specification of subcommands can be `defined in CommandBase.command`__
+  as a shortcut.
+
+__ https://github.com/babab/pycommand/commit/a978a05ef92f70f0ce6b06d96a38c2caa8297ecc
+
+0.1.0 - 2013-08-08
+------------------
+Added
+#####
+- Initial release

README.rst

@@ -1,40 +1,32 @@
+pycommand 0.2.0
+******************************************************************************
+
 .. image:: https://travis-ci.org/babab/pycommand.svg?branch=master
     :target: https://travis-ci.org/babab/pycommand
 
+**A clean and simplistic alternative for argparse, optparse and getopt**
 
-pycommand
-******************************************************************************
-
-**Parse command line arguments / define (sub)commands with minimal code**
+Pycommand is essentially a fancy wrapper around getopt that consists of
+one simple `CommandBase` class that you can use to create executable
+commands for your python programs with very simplistic and readable
+code. It has support for subcommands and also nesting commands, so you
+can create (multiple levels of) subcommands, with the ability to pass
+the values of optional arguments of a command object to its subcommand
+objects. Supported Python versions are 2.7 and 3.2 and later.
 
-Pycommand consists of one simple `CommandBase` class that you can use to
-create executable commands for your python programs with very simplistic
-and readable code. It has support for nesting commands, so you can
-create (multiple levels of) subcommands, with the ability to pass the
-values of optional arguments of a command object to its subcommand
-objects. Supported Python versions are 2.7, 3.2, 3.3 and 3.4
-
-Why was it created?
-===================
-
-When parsing command line program arguments, I sometimes work with
-`argparse` (a replacement for `optparse`). I don't really like the API
-and the output it gives, which is the main reason I've always used
-`getopt` for parsing arguments whenever possible.
-
-The `CommandBase` class was originally written for *DisPass*,
-which is a password manager/generator, as a means to easily define new
-subcommands and have auto-generated usage messages. Because I want to
-have this in other projects I've decided to put it in the cheeseshop.
 
 Download and install
 ====================
 
-If you have pip installed, you can just::
+If you have pip installed, you can just:
+
+.. code-block:: console
 
    # pip install pycommand
 
-Otherwise, do something like this::
+To work with the current development version, do something like this:
+
+.. code-block:: console
 
    $ git clone git://bitbucket.org/babab/pycommand.git
    # cd pycommand
@@ -44,10 +36,10 @@ Otherwise, do something like this::
 Quick setup from a template
 ===========================
 
-*(currently only available in the git version)*
-
 To quicly start writing a command from a template (much like the
-example below), just run::
+examples below), use pycommand's helper script by running:
+
+.. code-block:: console
 
    $ pycommand init
 
@@ -61,17 +53,38 @@ Example
 
 For full documentation and examples, visit http://pythonhosted.org/pycommand/
 
-Here is a little preview::
+Here is an undocumented code example of getting automated usage text
+generation and parsing of optional arguments. If we name the script
+for which you can see the code below ``basic-example`` and execute it,
+the following will be the output for running ``basic-example -h`` or
+``basic-example --help``:
+
+.. code-block:: console
+
+   usage: basic-example [options]
+
+   An example of a basic CLI program
+
+   Options:
+   -h, --help                        show this help information
+   -f <filename>, --file=<filename>  use specified file
+   --version                         show version information
+
+And here is the code:
+
+.. code-block:: python
 
    #!/usr/bin/env python
 
    import pycommand
    import sys
 
 
-   class Command(pycommand.CommandBase):
-       usagestr = 'usage: example-command [options]'
-       description = 'An example of a basic CLI program'
+   class BasicExampleCommand(pycommand.CommandBase):
+       '''An example of a basic CLI program'''
+       usagestr = 'usage: basic-example [options]'
+       description = __doc__
+
        optionList = (
            ('help', ('h', False, 'show this help information')),
            ('file', ('f', '<filename>', 'use specified file')),
@@ -81,36 +94,37 @@ Here is a little preview::
        def run(self):
            if self.flags['help']:
                print(self.usage)
-               return
+               return 0
            elif self.flags['version']:
                print('Python version ' + sys.version.split()[0])
-               return
+               return 0
            elif self.flags['file']:
                print('filename = ' + self.flags['file'])
-               return
+               return 0
 
            print('Program completed. Try adding "--help"')
 
    if __name__ == '__main__':
-       cmd = Command(sys.argv[1:])
+       cmd = BasicExampleCommand(sys.argv[1:])
        if cmd.error:
            print('error: {0}'.format(cmd.error))
            sys.exit(1)
        else:
            sys.exit(cmd.run())
 
 
-If we name this script ``example-comand`` and execute it, the following will be
-the output for running ``example-command -h`` or ``example-command --help``::
-
-   usage: example-command [options]
+Why was it created?
+===================
 
-   An example of a basic CLI program
+When parsing command line program arguments, I sometimes work with
+`argparse` (a replacement for `optparse`). I don't really like the API
+and the output it gives, which is the main reason I've always used
+`getopt` for parsing arguments whenever possible.
 
-   Options:
-   -h, --help                        show this help information
-   -f <filename>, --file=<filename>  use specified file
-   --version                         show version information
+The `CommandBase` class was originally written for *DisPass*,
+which is a password manager/generator, as a means to easily define new
+subcommands and have auto-generated usage messages. Because I want to
+have this in other projects I've decided to put it in the cheeseshop.
 
 
 Contributing

doc/index.rst

@@ -1,10 +1,9 @@
+pycommand 0.2.0
+******************************************************************************
+
 .. image:: https://travis-ci.org/babab/pycommand.svg?branch=master
     :target: https://travis-ci.org/babab/pycommand
 
-
-pycommand
-******************************************************************************
-
 .. toctree::
    :maxdepth: 2
 
@@ -19,7 +18,6 @@ the values of optional arguments of a command object to its subcommand
 objects. Supported Python versions are 2.7 and 3.2 and later.
 
 
-
 Download and install
 ====================
 
@@ -29,7 +27,7 @@ If you have pip installed, you can just:
 
    # pip install pycommand
 
-Otherwise, do something like this:
+To work with the current development version, do something like this:
 
 .. code-block:: console
 
@@ -56,7 +54,27 @@ shell script (for your Python package/module)).
 Example #1 - A Basic command
 ============================
 
-Here is a typical example of a very common command line interface program::
+Here is a demonstration of the automated usage text generation and
+parsing of optional arguments.
+
+If we name the script for which you can see the code below
+``basic-example`` and execute it, the following will be the output for
+running ``basic-example -h`` or ``basic-example --help``:
+
+.. code-block:: console
+
+   usage: basic-example [options]
+
+   An example of a basic CLI program
+
+   Options:
+   -h, --help                        show this help information
+   -f <filename>, --file=<filename>  use specified file
+   --version                         show version information
+
+And here is the code:
+
+.. code-block:: python
 
    #!/usr/bin/env python
 
@@ -136,26 +154,13 @@ Here is a typical example of a very common command line interface program::
            sys.exit(cmd.run())
 
 
-If we name this script ``basic-example`` and execute it, the following will be
-the output for running ``basic-example -h`` or ``basic-example --help``:
-
-.. code-block:: console
-
-   usage: basic-example [options]
-
-   An example of a basic CLI program
-
-   Options:
-   -h, --help                        show this help information
-   -f <filename>, --file=<filename>  use specified file
-   --version                         show version information
-
-
 Example #2 - Full example of one main command with two subcommands
 ==================================================================
 
 Here is a full example demonstrating essentially the same program, but
-with the ``--help`` and ``--version`` options replaced for subcommands::
+with the ``--help`` and ``--version`` options replaced for subcommands:
+
+.. code-block:: python
 
    #!/usr/bin/env python
 
@@ -258,7 +263,7 @@ with the ``--help`` and ``--version`` options replaced for subcommands::
        else:
            sys.exit(cmd.run())
 
-And here are some outputs:
+And here are some output examples:
 
 .. code-block:: console
 
@@ -325,6 +330,9 @@ sending pull-requests.
 - Github: https://github.com/babab/pycommand
 
 
+.. include:: ../CHANGELOG.rst
+
+
 Software license
 ================