Update documentation

docs/conf.py

@@ -52,7 +52,7 @@
 
 # General information about the project.
 project = u'sphinx-argparse'
-copyright = u'2013, Alex Rudakov'
+copyright = u'2016, Alex Rudakov, Devon Ryan and contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/contrib.rst

@@ -1,8 +1,5 @@
-
-
-
 Contribution
------------------------------------------
+============
 
 Any help is welcome!
 Most wanted:
@@ -21,4 +18,4 @@ Don't forget to run tests before commit::
 
     py.test
 
-Any feedback is welcome: ribozz (a) gmail dot com
+Any feedback is welcome: ribozz (a) gmail dot com

docs/extend.rst

@@ -1,19 +1,14 @@
+Extending results of `argparse` directives
+==========================================
 
-
-
-
-Extending result of `argparse` directive
------------------------------------------
-
-You can add extra content or even replace some part of documentation generated by `argparse` directive.
-For example, any content you put inside directive (follow reText identation rules), will be inserted, just before argument and option list::
+You can add extra content or even replace some parts of the documentation generated by the `argparse` directive. For example, any content you put inside directives (you must follow ReStructuredText identation rules) will be inserted just before the argument and option list::
 
    .. argparse::
        :module: my.module
        :func: my_func_that_return_parser
        :prog: fancytool
 
-       My content here that will be inserted as extra, right before argument list.
+       My content here that will be inserted right before the argument list.
 
        Also any valid markup...
        *************************
@@ -25,8 +20,7 @@ For example, any content you put inside directive (follow reText identation rule
             any directives you usually use.
 
 
-Also, there is an option to insert own content into argument/option/subcommand description. Just create definition-list,
-where name is argument/option/subcommand name and definition-body is any reStructured markup::
+Also, there is an option to insert custom content into a specific argument/option/subcommand description. Just create name:definition pair, where the name is an argument/option/subcommand name and the definition is any reStructured markup::
 
    .. argparse::
        :module: my.module
@@ -36,41 +30,39 @@ where name is argument/option/subcommand name and definition-body is any reStruc
        My content here that will be inserted as extra right before argument list.
 
        foo
-            This text will go right after "foo" positional argument help.
+            This text will go right after the "foo" positional argument help.
 
        install
-            This text will go right after "install" subcommand help and before it's arguments.
+            This text will go right after the "install" subcommand help and before its arguments.
 
             --upgrade
-                This text will go to upgrade option of install subcommand, nesting is not limited
+                This text will go after the upgrade option of the install subcommand. Nesting is unlimited.
 
 
-You can also add classifiers to definition-list that will change behavior of content merge algorythm::
+You can also add classifiers, which will change how these definitions are incorporated::
 
    .. argparse::
        :module: my.module
        :func: my_func_that_return_parser
        :prog: fancytool
 
-       My content that will be inserted as extra, right before argument list.
+       My content that will be inserted right before the argument list.
 
        foo : @before
-            This text will go right after "foo" positional argument help.
+            This text will go before the "foo" positional argument help.
 
        install : @replace
-            This text will go right after "install" subcommand help and befor it's arguments.
+            This text will replace the "install" subcommand help/description.
 
             --upgrade : @after
-                This text will go to upgrade option of install subcommand, nesting is not limited
+                The after directive is the default, so you needn't specify it.
 
 
 @before
-    Insert content before parsed help message of argument/option/subcommand.
+    Insert content before parsed help/description message of argument/option/subcommand.
 
 @after
-    Insert content after parsed help message of argument/option/subcommand.
-
-    This is default, if you do not specify classifier explicitly.
+    Insert content after parsed help/description message of argument/option/subcommand. This is the default.
 
 @replace
-    Replace content of help message of argument/option/subcommand.
+    Replace content of help/description message of argument/option/subcommand.

docs/index.rst

@@ -1,5 +1,5 @@
 `sphinx-argparse`
-=============================================================
+=================
 
 `sphinx-argparse` is extension for sphinx that allows easily generate documentation
 for command line tools based on argparse library.
@@ -19,11 +19,9 @@ for command line tools based on argparse library.
 
 
 References
-==================
+==========
 
 Similar projects
 -------------------
 
  * https://pythonhosted.org/sphinxcontrib-autoprogram/ (See for comparison: https://github.com/ribozz/sphinx-argparse/issues/16)
-
-

docs/install.rst

@@ -1,15 +1,12 @@
-
-
 Installation
-------------
+============
 
-This extension is tested on python 2.7. If you have successfully used it on any other version
-of python, then add this info to this doc please (through github pull request).
+This extension is tested on python 2.7 and 3.3+.
 
-Package is  available in the Python Package Index::
+Package is available in the Python Package Index::
 
     pip install sphinx-argparse
 
-Enable extension in your sphinx config::
+Enable the extension in your sphinx config::
 
     extensions += ['sphinxarg.ext']

docs/sample.rst

@@ -1,11 +1,10 @@
-==============
 Examples
-==============
+========
 
-Example structure of pages
-=============================
+Example documentation structure
+-------------------------------
 
-Here is example structure of documentation for complex commands with lots of subcommands.
+Here is an example structure for the documentation of a complex command with many subcommands. 
 You are free to use any structure, but this may be a good starting point.
 
 File "index.rst"::
@@ -36,7 +35,7 @@ File "cmd_main.rst"::
 
     .. argparse::
        :module: my.module
-       :func: my_func_that_return_parser
+       :func: my_func_that_returns_a_parser
        :prog: fancytool
 
        subcommand
@@ -57,18 +56,18 @@ File "cmd_subcommand.rst"::
 
 
 Source of example file
-===========================
+----------------------
 
 This file will be used in all generated examples.
 
 .. literalinclude:: ../test/sample.py
 
 
 Generated sample 1 - command with subcommands
-================================================
+---------------------------------------------
 
 Directive
-----------------
+~~~~~~~~~
 
 Source::
 
@@ -77,18 +76,18 @@ Source::
        :prog: sample
 
 Output
-----------------
+~~~~~~
 
 .. argparse::
    :ref: test.sample.parser
    :prog: sample
 
 
 Generated sample 2 - subcommand
-==================================
+-------------------------------
 
 Directive
-----------------
+~~~~~~~~~
 
 Source::
 
@@ -99,10 +98,10 @@ Source::
        :path: game
 
 Output
-----------------
+~~~~~~
 
 .. argparse::
    :module: test.sample
    :func: parser
    :prog: sample
-   :path: game
+   :path: game

docs/usage.rst

@@ -1,29 +1,26 @@
-
-
-
 Basic usage
------------------
+===========
 
-Extension adds "argparse" directive::
+This extension adds the "argparse" directive::
 
     .. argparse::
        :module: my.module
        :func: my_func_that_returns_a_parser
        :prog: fancytool
 
-`module`, `func` and `prog` options are required.
+The `module`, `func` and `prog` options are required.
 
-func is function that returns an instance of the `argparse.ArgumentParser` class.
+`func` is a function that returns an instance of the `argparse.ArgumentParser` class.
 
-Alternative syntax is to use :ref: like this::
+Alternatively, one can instead use :ref: like this::
 
     .. argparse::
        :ref: my.module.my_func_that_returns_a_parser
        :prog: fancytool
 
-in this case :ref: also may point directly to argument parser instance.
+In this case :ref: also may point directly to argument parser instance.
 
-For this directive to work, you should point it to the function, that will return pre-filled `ArgumentParser`.
+For this directive to work, you should point it to the function that will return a pre-filled `ArgumentParser`.
 Something like::
 
     def my_func_that_return_parser():
@@ -68,8 +65,7 @@ To document a file that is not part of a module, use :filename::
 
 That's it. Directives will render positional arguments, options and sub-commands.
 
-Sub-commands are limited to one level. But, you always can output help for subcommands separately::
-
+Sub-commands are limited to one level. But, you can always output help for subcommands separately::
 
     .. argparse::
        :module: my.module
@@ -89,8 +85,8 @@ Nesting level is not limited::
 
 
 Other useful directives
------------------------------------------
+-----------------------
 
 :nodefault: will hide all default values of options.
 
-:nodefaultconst: Like nodefault:, expect it applies only to arguments of types `store_const`, `store_true` and `store_false`.
+:nodefaultconst: Like nodefault:, except it applies only to arguments of types `store_const`, `store_true` and `store_false`.

setup.py

@@ -13,7 +13,7 @@
     license='MIT',
     author='Aleksandr Rudakov',
     author_email='[email protected]',
-    description='Sphinx extension that automatically document argparse commands and options',
+    description='Sphinx extension that automatically documents argparse commands and options',
     long_description='',
     install_requires=deps,