collect metavar name for all arguments

The metavar is the name of the "value" available for arguments and
for some options. Typical example would be --output FILE. FILE is the
metavar string.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
do not collect options that contain the string ==SUPPRESS==

==SUPPRESS== is the magic value used by argparse to hide command line
options. We should follow the same behavior.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
collect bare_usage, a vesion of usage without the i18n "usage: " prefix

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
collect parser 'prog' (program name) for completeness

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
do not override parser.prog unconditionally

The :prog: argument to the .. argparse:: directive allows programmers
to override the program name but prog is typically correctly inferred
by argparse, and in some situations, it is already provided to argparse
explicitly. To keep code DRY, we should not override it without
having an explicit value

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
minor formatting changes for closing parentheses

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
minor formatting changes, remove some useless newlines

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
add special :manpage: mode

This mode is changing the way the directive is impacting the resulting
document. The layout changes to traditional manpage SYNOPSIS, DESCRIPTION,
etc sections. Most of the content is expected to be provided either
inline in the nested definitions (indented text below .. argparse::)
and immediately after that (for sections other than DESCRIPTION).

A number of existing sphinxarg features are not supported yet.
Specifically none of the @before @after and @replace pseudo-decorators
are handled.

Some of the new private methods are re-implementations of similar methods
from the generic code path but they could not be reused at this time.

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
sort imports

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>
tox-test on python3.4

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>