--- a/docs/_static/cleanery.css	Wed Jan 26 19:14:22 2011 +0100
+++ b/docs/_static/cleanery.css	Wed Jan 26 19:46:19 2011 +0100
@@ -1,7 +1,7 @@
 @import url("default.css");
 
 body {
-    max-width: 60em;
+    max-width: 50em;
     margin: 0 auto;
     background-color: white;
 }

--- a/docs/conf.py	Wed Jan 26 19:14:22 2011 +0100
+++ b/docs/conf.py	Wed Jan 26 19:46:19 2011 +0100
@@ -20,7 +20,7 @@
 # -- Options for HTML output ---------------------------------------------------
 
 html_theme = 'default'
-html_style = 'custom.css'
+html_style = 'cleanery.css'
 html_theme_options = {'nosidebar': True}
 html_title = "%s v%s" % (project, version)
 html_static_path = ['_static']

--- a/docs/index.rst	Wed Jan 26 19:14:22 2011 +0100
+++ b/docs/index.rst	Wed Jan 26 19:46:19 2011 +0100
@@ -1,6 +1,6 @@
-=============
+========
  Opster
-=============
+========
 
 Opster is a command line parser, intended to make writing command line
 applications easy and painless. It uses built-in Python types (lists,
@@ -14,13 +14,59 @@
 Features
 --------
 
-- parsing arguments from sys.argv or custom strings
-- converting from string to appropriate Python objects
-- help message generation
-- positional and named arguments
-- subcommands support
+- parsing arguments from ``sys.argv`` or custom strings
+- :ref:`converting <options-processing>` from string to appropriate Python
+  objects
+- :ref:`help message <help-generation>` generation
+- positional and named arguments (i.e. arguments and options)
+- :ref:`subcommands <subcommands>` support
 - short, clean and concise definitions
-- ability to shorten names of subcommand and long options
+- :ref:`ability to shorten <partial-names>` names of subcommand and long options
+
+Quick example
+-------------
+
+That's an example of an option definition::
+
+  import sys
+  from opster import command
+
+  @command(usage='%name [-n] MESSAGE')
+  def main(message,
+           no_newline=('n', False, "don't print a newline")):
+      'Simple echo program'
+      sys.stdout.write(message)
+      if not no_newline:
+          sys.stdout.write('\n')
+
+  if __name__ == '__main__':
+      main()
+
+Running this program will print the help::
+
+  > ./echo.py
+  echo.py: invalid arguments
+  echo.py [-n] MESSAGE
+
+  Simple echo program
+
+  options:
+
+   -n --no-newline  don't print a newline
+   -h --help        show help
+
+As you can see, here we have defined option to not print newline: keyword
+argument name is a long name for option, default value is a 3-tuple, containing
+short name for an option (can be empty), default value (on base of which
+processing is applied - :ref:`see description <options-processing>`) and a help
+string.
+
+Underscores in long names are converted into dashes.
+
+If you are calling a command with option using long name, you can supply it
+partially. In this case it could look like ``./echo.py --nonew``. This is also
+true for subcommands: read about them and everything else you'd like to know
+further in documentation.
 
 What's nice
 -----------

--- a/docs/overview.rst	Wed Jan 26 19:14:22 2011 +0100
+++ b/docs/overview.rst	Wed Jan 26 19:46:19 2011 +0100
@@ -3,7 +3,7 @@
 ==============
 
 Options
--------
+=======
 
 Configuration of option parser is a list of tuples::
 
@@ -13,35 +13,35 @@
           ('', 'pid-file', '', 'name of file to write process ID to')]
 
 Options contents
-^^^^^^^^^^^^^^^^
+----------------
 
 Each tuple is a definition of some option, consisting of 4 elements:
 
- 1. short name
- 2. long name (read note_)
- 3. default value
- 4. help string
+1. short name
+2. long name (read :ref:`note <renaming-note>`)
+3. default value
+4. help string
 
 If a short name renders to False (for example, empty string), then it's not used
 at all. Long name is pretended to be available in any case.
 
+.. _options-processing:
+
 Options processing
-^^^^^^^^^^^^^^^^^^
+------------------
 
 Default value also determines how supplied argument should be parsed:
 
- - function: return value of function called with a specified value is passed
- - integer: value is convert to integer
- - string: value is passed as is
- - list: value is appended to this list
- - dictionary: value is then assumed being in format ``key=value`` and is
-   then assigned to this dictionary, `example`_
- - boolean/None: ``not default`` is passed and option takes no value
-
-.. _example: http://hg.piranha.org.ua/opster/file/default/tests/opster.t#l109
+- function: return value of function called with a specified value is passed
+- integer: value is convert to integer
+- string: value is passed as is
+- list: value is appended to this list
+- dictionary: value is then assumed being in format ``key=value`` and is
+  then assigned to this dictionary, :ref:`example <definitions-test>`
+- boolean/None: ``not default`` is passed and option takes no value
 
 Usage
-^^^^^
+-----
 
 Usage is easy like that::
 
@@ -60,14 +60,15 @@
            pid_file=('', '', 'name of file to write process ID to')):
       pass
 
-.. _note:
+.. _renaming-note:
+.. note::
 
-I think it's easy to understand what's going on here, except that you need to
-know that underscores in the long name will be replaced with dashes at the
-command line. Of course, reverse process happens: if you have option with a dash
-in long name in a definition, it will be replaced with underscore when passed to
-function. This is done to comply with standarts of writing both console
-interfaces and Python application.
+  I think it's easy to understand what's going on here, except that you need to
+  know that underscores in the long name will be replaced with dashes at the
+  command line. Of course, reverse process happens: if you have option with a
+  dash in long name in a definition, it will be replaced with underscore when
+  passed to function. This is done to comply with standarts of writing both
+  console interfaces and Python applications.
 
 After that you can simply call this function as an entry point to your program::
 
@@ -92,8 +93,10 @@
 In this case no type conversion (which is done upon arguments parsing) will be
 performed.
 
+.. _subcommands:
+
 Subcommands
------------
+===========
 
 It's pretty usual for complex application to have some system of subcommands,
 and opster provides facility for handling them. Configuration is simple::
@@ -144,11 +147,13 @@
   if __name__ == '__main__':
       dispatch(cmdtable=cmdtable)
 
+.. _partial-names:
+
 Example usage, calling ``complex_`` with 5 as an argument for ``exit`` option,
 shows that command dispatcher will understand partial names of commands and
 options::
 
-  app har --ex 5
+  app comp --ex 5
 
 But if your program is something like program shown earlier, you can use
 shortened api::
@@ -165,8 +170,10 @@
 special global command table, which allows to call ``dispatch()`` without
 arguments.
 
+.. _help-generation:
+
 Help generation
----------------
+===============
 
 Help is generated automatically and is available by the ``-h/--help`` command
 line option or by ``help`` subcommand (if you're using subcommand system).
@@ -203,7 +210,7 @@
 
 
 Tips and tricks
----------------
+===============
 
 There is one thing which may be obvious: it's easy to have "semi-global"
 options. If your subcommands (or scripts) tend to have same options in some

--- a/tests/opster.t	Wed Jan 26 19:14:22 2011 +0100
+++ b/tests/opster.t	Wed Jan 26 19:46:19 2011 +0100
@@ -107,6 +107,8 @@
    'port': 5656,
    'test': 'test'}
 
+.. _definitions-test:
+
 Now let's test our definitions::
 
   $ run test_opts.py -D a=b so-what?