Merge branch 'release/0.1.16'

.travis.yml

@@ -1,15 +1,13 @@
 language: python
 python:
-  - "2.6"
   - "2.7"
   - "3.3"
+  - "3.4"
+  - "3.5"
 install:
-- "pip install -e .[dev]"
+ - pip install .
+ - pip install flake8
 
 script:
-- py.test
-
-notifications:
-  email:
-    recipients:
-      - [email protected]
+ - py.test
+ - flake8 . --ignore=E501 --exclude=docs/conf.py

README.md

@@ -1,10 +1,9 @@
+[![Build Status](https://travis-ci.org/ribozz/sphinx-argparse.svg?branch=master)](https://travis-ci.org/ribozz/sphinx-argparse) [![Documentation Status](https://readthedocs.org/projects/sphinx-argparse/badge/)](http://sphinx-argparse.readthedocs.org/) [![PyPI version](https://badge.fury.io/py/sphinx-argparse.svg)](https://badge.fury.io/py/sphinx-argparse)
+
 sphinx-argparse
 ===============
 
-:exclamation: **NB** :exclamation: New maintainer needed! Looking for person who actively use sphinx-argparse, love it and willing to help with it's development. Contact me by mail: [email protected]
-
-
-Sphinx extension that automatically document argparse commands and options
+Sphinx extension that automatically documents argparse commands and options
 
 For installation and usage details see docs.
 
@@ -13,18 +12,25 @@ http://sphinx-argparse.readthedocs.org/en/latest/
 
 
 Changelog & contributors
-------------------------------
+========================
 
-0.1.15
+0.1.16
+------
 
-------------------------------
+- Added a `:nodefaultconst:` directive, which is similar to the `:nodefault:` directive, but applies only to `store_true`, `store_false`, and `store_const` (e.g., it will hide the "=True" part in the output, since that can be misleading to users).
+- Fixed various typos (thanks to users mikeantonacci, brondsem, and tony)
+- Format specifiers (e.g., `%(prog)s` and `%(default)s`) are now filled in (if possible) in help sections. If there's a missing keyword, then nothing will be filled in. This was issue #27.
+- The package is now a bit more robust to incorrectly spelling module names (#39, courtesy of Gabriel Falcão)
+- Added support for argparse groups (thanks to Fidel Ramirez)
+
+0.1.15
+------
 
 - Fixed malformed docutils DOM in manpages (Matt Boyer)
 
 
 0.1.14
-
------------------------------
+------
 
 - Support for aliasing arguments #22 (Campbell Barton)
 - Support for nested arguments #23 (Campbell Barton)
@@ -33,69 +39,67 @@ Changelog & contributors
 - Added 'passparser' option (David Hoese)
 
 0.1.13
-
------------------------------
+------
 
 - Bugfix: Choices are not always strings (Robert Langlois)
 - Polished small mistakes in usage documentation (Dean Malmgren)
 - Started to improve man-pages support (Zygmunt Krynicki)
 
-------------------------------
 0.1.12
+------
 
 - Improved error reporting (James Anderson)
 
-------------------------------
 0.1.11
+------
 
 - Fixed stupid bug, prevented things working on py3 (Alex Rudakov)
 - added tox configuration for tests
 
-------------------------------
 0.1.10
+------
 
 - Remove the ugly new line in the end of usage string (Vadim Markovtsev)
 - Issue #9 Display argument choises (Proposed by Felix-neko, done by Alex Rudakov)
 - :ref: syntax for specifying path to parser instance. Issue #7 (Proposed by David Cottrell, Implemented by Alex Rudakov)
 - Updated docs to read the docs theme
 
-------------------------------
 0.1.9
+-----
 
 Fix problem with python version comparison, when python reports it as "2.7.5+" (Alex Rudakov)
 
-------------------------------
 0.1.8
+-----
 
 Argparse is not required anymore separate module as of python 2.7 (Mike Gleen)
 
-------------------------------
 0.1.7
+-----
 
 -- Nothing -- Created by axident.
 
-------------------------------
 0.1.6
+-----
 
 Adding :nodefault: directive that skips default values for options (Stephen Tridgell)
 
-------------------------------
 0.1.5
+-----
 
 Fix issue: epilog is ignored (James Anderson - https://github.com/jamesra)
 
-------------------------------
 0.1.4
+-----
 
 Fix issue #3: ==SUPPRESS== in option list with no default value
 
-------------------------------
 0.1.2
+-----
 
 Fix issue with subcommands (by Tony Narlock - https://github.com/tony)
 
-------------------------------
 0.1.1
+-----
 
 Initial version
-

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.
@@ -13,16 +13,15 @@ for command line tools based on argparse library.
    usage
    extend
    sample
+   misc
    contrib
 
 
 
 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/misc.rst

@@ -0,0 +1,21 @@
+Miscellaneous
+=============
+
+Text wrapping in argument tables
+--------------------------------
+
+A common issue with the default html output is that the table within which options are displayed is designed such that the option descriptions are each held on one line. Any even remotely lengthy description then causes the viewer to need to scroll left/right to view the entire text. This is typically undesirable and the fix is described fully `here <http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html>`_.
+
+The short synopsis is below:
+
+ 1. Create a new CSS file (likely under `_static`) and point to it in `html_static_path` and `html_context` (or a template in the `templates_path`) in `conf.py`.
+ 2. In that CSS file, add the following code::
+
+.. code:: CSS
+
+    .wy-table-responsive table td {
+        white-space: normal !important;
+    }
+    .wy-table-responsive {
+        overflow: visible !important;
+    }