add support for generating man page descriptions from code

For scripts, the initial line in the module's docstring will be the
summary description and any remaining lines will be used for the verbose
description in the man page.

If the docstring only has one line then the summary is also used for the
description.

18 files changed, 24 insertions, 64 deletions

diff --git a/doc/man/filter-env.rst b/doc/man/filter-env.rst
index ff9b75092..e51f38a5b 100644
--- a/doc/man/filter-env.rst
+++ b/doc/man/filter-env.rst
@@ -3,10 +3,5 @@ filter-env
 ==========
 
 .. include:: filter-env/main_synopsis.rst
-
-Description
-===========
-
-filter a bash environment dump
-
+.. include:: filter-env/main_description.rst
 .. include:: filter-env/main_options.rst
diff --git a/doc/man/pclonecache.rst b/doc/man/pclonecache.rst
index d7cd3be2b..438fb8f99 100644
--- a/doc/man/pclonecache.rst
+++ b/doc/man/pclonecache.rst
@@ -3,10 +3,5 @@ pclonecache
 ===========
 
 .. include:: pclonecache/main_synopsis.rst
-
-Description
-===========
-
-pkgcore repository cache clone utility
-
+.. include:: pclonecache/main_description.rst
 .. include:: pclonecache/main_options.rst
diff --git a/doc/man/pconfig.rst b/doc/man/pconfig.rst
index de16040a9..c8b5f2f9d 100644
--- a/doc/man/pconfig.rst
+++ b/doc/man/pconfig.rst
@@ -3,10 +3,5 @@ pconfig
 =======
 
 .. include:: pconfig/main_synopsis.rst
-
-Description
-===========
-
-pkgcore configuration querying utility
-
+.. include:: pconfig/main_description.rst
 .. include:: pconfig/main_options.rst
diff --git a/doc/man/pebuild.rst b/doc/man/pebuild.rst
index 0b854547a..bc334ba21 100644
--- a/doc/man/pebuild.rst
+++ b/doc/man/pebuild.rst
@@ -3,10 +3,5 @@ pebuild
 =======
 
 .. include:: pebuild/main_synopsis.rst
-
-Description
-===========
-
-pkgcore low-level ebuild utility
-
+.. include:: pebuild/main_description.rst
 .. include:: pebuild/main_options.rst
diff --git a/doc/man/pinspect.rst b/doc/man/pinspect.rst
index 221e4acef..076f09b26 100644
--- a/doc/man/pinspect.rst
+++ b/doc/man/pinspect.rst
@@ -3,10 +3,5 @@ pinspect
 ========
 
 .. include:: pinspect/main_synopsis.rst
-
-Description
-===========
-
-pkgcore repository inspection interface
-
+.. include:: pinspect/main_description.rst
 .. include:: pinspect/main_options.rst
diff --git a/doc/man/pmaint.rst b/doc/man/pmaint.rst
index d46783473..dbc40bd40 100644
--- a/doc/man/pmaint.rst
+++ b/doc/man/pmaint.rst
@@ -3,10 +3,5 @@ pmaint
 ======
 
 .. include:: pmaint/main_synopsis.rst
-
-Description
-===========
-
-pkgcore system/repository maintenance utility
-
+.. include:: pmaint/main_description.rst
 .. include:: pmaint/main_options.rst
diff --git a/doc/man/pmerge.rst b/doc/man/pmerge.rst
index ccd47e639..ff22f971f 100644
--- a/doc/man/pmerge.rst
+++ b/doc/man/pmerge.rst
@@ -3,13 +3,7 @@ pmerge
 ======
 
 .. include:: pmerge/main_synopsis.rst
-
-Description
-===========
-
-pmerge is the main command-line utility for merging and unmerging packages on a
-system. It provides an interface to install, update, and uninstall ebuilds from
-source or binary packages.
+.. include:: pmerge/main_description.rst
 
 Portage Compatibility
 =====================
diff --git a/doc/man/pplugincache.rst b/doc/man/pplugincache.rst
index e1fb66009..2cf39770f 100644
--- a/doc/man/pplugincache.rst
+++ b/doc/man/pplugincache.rst
@@ -3,10 +3,5 @@ pplugincache
 ============
 
 .. include:: pplugincache/main_synopsis.rst
-
-Description
-===========
-
-pkgcore plugin cache update utility
-
+.. include:: pplugincache/main_description.rst
 .. include:: pplugincache/main_options.rst
diff --git a/pkgcore/scripts/filter_env.py b/pkgcore/scripts/filter_env.py
index 2af666217..77f4fe434 100644
--- a/pkgcore/scripts/filter_env.py
+++ b/pkgcore/scripts/filter_env.py
@@ -14,7 +14,7 @@ from pkgcore.util import commandline
 
 argparser = commandline.mk_argparser(
     config=False, domain=False, verbose=False, color=False,
-    description=__doc__.split('\n', 1)[0])
+    description=__doc__)
 
 def stdin_default(namespace, attr):
     if sys.stdin.isatty():
diff --git a/pkgcore/scripts/pclonecache.py b/pkgcore/scripts/pclonecache.py
index 740352f55..aec934c75 100644
--- a/pkgcore/scripts/pclonecache.py
+++ b/pkgcore/scripts/pclonecache.py
@@ -11,7 +11,7 @@ import time
 from pkgcore.util import commandline
 
 argparser = commandline.mk_argparser(
-    domain=False, description=__doc__.split('\n', 1)[0])
+    domain=False, description=__doc__)
 argparser.add_argument(
     "source", config_type='cache',
     action=commandline.StoreConfigObject,
diff --git a/pkgcore/scripts/pconfig.py b/pkgcore/scripts/pconfig.py
index 4b6a5280d..bba14afdf 100644
--- a/pkgcore/scripts/pconfig.py
+++ b/pkgcore/scripts/pconfig.py
@@ -108,7 +108,7 @@ shared_options = (commandline.mk_argparser(
     config=False, color=False, version=False, domain=False, add_help=False),)
 argparser = commandline.mk_argparser(
     suppress=True, parents=(commandline.mk_argparser(domain=False, add_help=False),),
-    description=__doc__.split('\n', 1)[0])
+    description=__doc__)
 subparsers = argparser.add_subparsers(description="configuration related subcommands")
 classes = subparsers.add_parser(
     "classes", parents=shared_options,
diff --git a/pkgcore/scripts/pebuild.py b/pkgcore/scripts/pebuild.py
index 48823ab90..bb509487a 100644
--- a/pkgcore/scripts/pebuild.py
+++ b/pkgcore/scripts/pebuild.py
@@ -14,7 +14,7 @@ from pkgcore.ebuild.errors import MalformedAtom
 from pkgcore.operations import observer
 from pkgcore.util import commandline
 
-argparser = commandline.mk_argparser(description=__doc__.split('\n', 1)[0])
+argparser = commandline.mk_argparser(description=__doc__)
 argparser.add_argument(
     'target', metavar='<atom|ebuild>',
     help="atom or ebuild matching a pkg to execute phases from")
diff --git a/pkgcore/scripts/pinspect.py b/pkgcore/scripts/pinspect.py
index 624ba3450..575a272d8 100644
--- a/pkgcore/scripts/pinspect.py
+++ b/pkgcore/scripts/pinspect.py
@@ -27,8 +27,7 @@ demandload(
 
 shared = (commandline.mk_argparser(domain=False, add_help=False),)
 argparser = commandline.mk_argparser(
-    suppress=True, parents=shared,
-    description=__doc__.split('\n', 1)[0])
+    suppress=True, parents=shared, description=__doc__)
 subparsers = argparser.add_subparsers(description="report applets")
 
 pkgsets = subparsers.add_parser("pkgsets", description="pkgset related introspection")
diff --git a/pkgcore/scripts/pmaint.py b/pkgcore/scripts/pmaint.py
index 118fcb401..ba9881345 100644
--- a/pkgcore/scripts/pmaint.py
+++ b/pkgcore/scripts/pmaint.py
@@ -38,9 +38,8 @@ demandload(
 
 
 argparser = commandline.mk_argparser(
-    suppress=True,
-    parents=(commandline.mk_argparser(domain=False, add_help=False),),
-    description=__doc__.split('\n', 1)[0])
+    suppress=True, description=__doc__,
+    parents=(commandline.mk_argparser(domain=False, add_help=False),))
 subparsers = argparser.add_subparsers(description="general system maintenance")
 
 shared_options = (commandline.mk_argparser(
diff --git a/pkgcore/scripts/pmerge.py b/pkgcore/scripts/pmerge.py
index b49fca97e..0f75fbd66 100644
--- a/pkgcore/scripts/pmerge.py
+++ b/pkgcore/scripts/pmerge.py
@@ -50,8 +50,7 @@ class StoreTarget(argparse._AppendAction):
             namespace.targets = []
 
 
-argparser = commandline.mk_argparser(
-    domain=True, description=__doc__.split('\n', 1)[0])
+argparser = commandline.mk_argparser(domain=True, description=__doc__)
 argparser.add_argument(
     nargs='*', dest='targets', metavar='TARGET', action=StoreTarget,
     help="extended package matching",
diff --git a/pkgcore/scripts/pplugincache.py b/pkgcore/scripts/pplugincache.py
index a97af8d61..37153a1b0 100644
--- a/pkgcore/scripts/pplugincache.py
+++ b/pkgcore/scripts/pplugincache.py
@@ -14,8 +14,7 @@ from pkgcore import plugin, plugins
 from pkgcore.util import commandline
 
 argparser = commandline.mk_argparser(
-    config=False, domain=False, color=False,
-    description=__doc__.split('\n', 1)[0])
+    config=False, domain=False, color=False, description=__doc__)
 argparser.add_argument(
     "packages", nargs="*", action='store',
     type=partial(commandline.python_namespace_type, module=True),
diff --git a/pkgcore/scripts/pquery.py b/pkgcore/scripts/pquery.py
index 732ec3af4..d3783c61f 100644
--- a/pkgcore/scripts/pquery.py
+++ b/pkgcore/scripts/pquery.py
@@ -426,8 +426,7 @@ def print_packages_noversion(options, out, err, pkgs):
 # priority 100:
 #  default priority for DelayedValue; anything else is setup then.
 
-argparser = commandline.mk_argparser(
-    domain=True, description=__doc__.split('\n', 1)[0])
+argparser = commandline.mk_argparser(domain=True, description=__doc__)
 
 repo_group = argparser.add_argument_group(
     'Repository matching options',
diff --git a/pkgcore/util/commandline.py b/pkgcore/util/commandline.py
index 110c6c0b9..9c4871cc0 100644
--- a/pkgcore/util/commandline.py
+++ b/pkgcore/util/commandline.py
@@ -601,6 +601,12 @@ class ArgumentParser(argparse.ArgumentParser):
                  conflict_handler='error',
                  add_help=True):
 
+        self.long_description = None
+        if description is not None:
+            description_lines = description.split('\n')
+            description = description_lines[0]
+            self.long_description = ' '.join(description_lines[1:]).strip()
+
         super(ArgumentParser, self).__init__(
             prog=prog, usage=usage,
             description=description, epilog=epilog,