Merge remote-tracking branch 'remotes/origin/samthursfield/update-help'

8 files changed, 121 insertions, 162 deletions

diff --git a/morphlib/app.py b/morphlib/app.py
index f4dd3403..8769b41c 100755
--- a/morphlib/app.py
+++ b/morphlib/app.py
@@ -56,117 +56,120 @@ class Morph(cliapp.Application):
                               'show what is happening in much detail')
         self.settings.boolean(['quiet', 'q'],
                               'show no output unless there is an error')
+
+        self.settings.string(['cachedir'],
+                             'cache git repositories and build results in DIR',
+                             metavar='DIR',
+                             default=defaults['cachedir'])
+        self.settings.string(['build-ref-prefix'],
+                             'Prefix to use for temporary build refs',
+                             metavar='PREFIX',
+                             default=defaults['build-ref-prefix'])
         self.settings.string(['trove-host'],
                              'hostname of Trove instance',
                              metavar='TROVEHOST',
                              default=defaults['trove-host'])
         self.settings.string_list(['trove-prefix'],
-                                  'define URL prefix aliases stored '
-                                  'directly on the Trove host.  Uses '
-                                  'the form '
-                                  'alias=pathprefix#pullmethod#pushmethod '
-                                  'for example, foocorp=fooprojects#git#ssh '
-                                  'will be expanded into a repo-alias of '
-                                  'foocorp=git://trove-host/fooprojects/%s#...'
-                                  ' with the push side set to the ssh url to '
-                                  'the trove.',\
-                                  metavar='ALIAS=PREFIX#PULL#PUSH',
+                                  'list of URL prefixes that should be '
+                                  'resolved to Trove',
+                                  metavar='PREFIX, ...',
                                   default=defaults['trove-prefix'])
+
+        group_advanced = 'Advanced Options'
+        self.settings.boolean(['no-git-update'],
+                              'do not update the cached git repositories '
+                              'automatically',
+                              group=group_advanced)
         self.settings.string_list(['repo-alias'],
-                                  'define URL prefix aliases to allow '
-                                  'repository addresses to be shortened; '
-                                  'use alias=pullpattern=pushpattern '
-                                  'to allow alias:shortname to be used '
-                                  'instead of the full URL; the patterns must '
-                                  'contain a %s where the shortname gets '
-                                  'replaced',
-                                  default=defaults['repo-alias'])
-        self.settings.string(['tarball-server'],
-                             'base URL to download tarballs. '
-                             'If not provided, defaults to '
-                             'http://TROVEHOST/tarballs/',
-                             metavar='URL',
-                             default=None)
+                                  'list of URL prefix definitions, in the '
+                                  'form: example=git://git.example.com/%s'
+                                  '#git@git.example.com/%s',
+                                  metavar='ALIAS=PREFIX#PULL#PUSH',
+                                  default=defaults['repo-alias'],
+                                  group=group_advanced)
         self.settings.string(['cache-server'],
                              'HTTP URL of the morph cache server to use. '
                              'If not provided, defaults to '
                              'http://TROVEHOST:8080/',
                              metavar='URL',
-                             default=None)
-        self.settings.string(['cachedir'],
-                             'put build results in DIR',
-                             metavar='DIR',
-                             default=defaults['cachedir'])
-        self.settings.string(['prefix'],
-                             'build chunks with prefix PREFIX',
-                             metavar='PREFIX', default=defaults['prefix'])
-        self.settings.string(['toolchain-target'],
-                             'set the TOOLCHAIN_TARGET variable which is used '
-                             'in some chunks to determine which architecture '
-                             'to build tools for',
-                             metavar='TOOLCHAIN_TARGET',
-                             default=defaults['toolchain-target'])
-        self.settings.string(['target-cflags'],
-                             'inject additional CFLAGS into the environment '
-                             'that is used to build chunks',
-                             metavar='CFLAGS',
-                             default='')
-        self.settings.string(['tempdir'],
-                             'temporary directory to use for builds '
-                             '(this is separate from just setting $TMPDIR '
-                             'or /tmp because those are used internally '
-                             'by things that cannot be on NFS, but '
-                             'this setting can point at a directory in '
-                             'NFS)',
-                             metavar='DIR',
-                             default=os.environ.get('TMPDIR'))
-        self.settings.boolean(['no-ccache'], 'do not use ccache')
+                             default=None,
+                             group=group_advanced)
+        self.settings.string(['tarball-server'],
+                             'base URL to download tarballs. '
+                             'If not provided, defaults to '
+                             'http://TROVEHOST/tarballs/',
+                             metavar='URL',
+                             default=None,
+                             group=group_advanced)
+
+        # Build Options
+        group_build = 'Build Options'
+        self.settings.boolean(['bootstrap'],
+                              'build stuff in bootstrap mode; this is '
+                              'DANGEROUS and will install stuff on your '
+                              'system',
+                              group=group_build)
         self.settings.string(['ccache-remotedir'],
                              'allow ccache to download objects from REMOTEDIR '
                              'if they are not cached locally',
                              metavar='REMOTEDIR',
-                             default=defaults['ccache-remotedir'])
+                             default=defaults['ccache-remotedir'],
+                             group=group_build)
         self.settings.integer(['ccache-remotenlevels'],
                               'assume ccache directory objects are split into '
                               'NLEVELS levels of subdirectories',
                               metavar='NLEVELS',
-                              default=defaults['ccache-remotenlevels'])
-        self.settings.boolean(['no-distcc'], 'do not use distcc')
+                              default=defaults['ccache-remotenlevels'],
+                              group=group_build)
+        self.settings.boolean(['keep-path'],
+                              'do not touch the PATH environment variable',
+                              group=group_build)
         self.settings.integer(['max-jobs'],
                               'run at most N parallel jobs with make (default '
                               'is to a value based on the number of CPUs '
                               'in the machine running morph',
                               metavar='N',
-                              default=defaults['max-jobs'])
-        self.settings.boolean(['keep-path'],
-                              'do not touch the PATH environment variable')
-        self.settings.boolean(['bootstrap'],
-                              'build stuff in bootstrap mode; this is '
-                              'DANGEROUS and will install stuff on your '
-                              'system')
-        self.settings.boolean(['ignore-submodules'],
-                              'do not cache repositories of git submodules '
-                              'or unpack them into the build directory')
-
-        self.settings.boolean(['no-git-update'],
-                              'do not update the cached git repositories '
-                              'during a build (user must have done that '
-                              'already using the update-gits subcommand)')
-
-        self.settings.string_list(['staging-filler'],
-                                  'unpack BLOB into staging area for '
-                                  'non-bootstrap builds (this will '
-                                  'eventually be replaced with proper '
-                                  'build dependencies)',
-                                  metavar='BLOB')
+                              default=defaults['max-jobs'],
+                              group=group_build)
+        self.settings.boolean(['no-ccache'], 'do not use ccache',
+                              group=group_build)
+        self.settings.boolean(['no-distcc'], 'do not use distcc',
+                              group=group_build)
+        self.settings.string(['prefix'],
+                             'build chunks with prefix PREFIX',
+                             metavar='PREFIX', default=defaults['prefix'],
+                             group=group_build)
         self.settings.boolean(['staging-chroot'],
-                              'build things in a staging chroot '
-                              '(require real root to use)')
-
-        self.settings.string(['build-ref-prefix'],
-                             'Prefix to use for temporary build refs',
-                             metavar='PREFIX',
-                             default=defaults['build-ref-prefix'])
+                              'build things in an isolated chroot '
+                              '(default: true)',
+                              group=group_build)
+        self.settings.string_list(['staging-filler'],
+                                  'use FILE as contents of build chroot',
+                                  metavar='FILE',
+                                  group=group_build)
+        self.settings.string(['target-cflags'],
+                             'inject additional CFLAGS into the environment '
+                             'that is used to build chunks',
+                             metavar='CFLAGS',
+                             default='',
+                             group=group_build)
+        self.settings.string(['tempdir'],
+                             'temporary directory to use for builds '
+                             '(this is separate from just setting $TMPDIR '
+                             'or /tmp because those are used internally '
+                             'by things that cannot be on NFS, but '
+                             'this setting can point at a directory in '
+                             'NFS)',
+                             metavar='DIR',
+                             default=os.environ.get('TMPDIR'),
+                             group=group_build)
+        self.settings.string(['toolchain-target'],
+                             'set the TOOLCHAIN_TARGET variable which is used '
+                             'in some chunks to determine which architecture '
+                             'to build tools for',
+                             metavar='TOOLCHAIN_TARGET',
+                             default=defaults['toolchain-target'],
+                             group=group_build)
 
     def check_time(self):
         # Check that the current time is not far in the past.
diff --git a/morphlib/plugins/branch_and_merge_plugin.py b/morphlib/plugins/branch_and_merge_plugin.py
index 2c5d1847..1646356d 100644
--- a/morphlib/plugins/branch_and_merge_plugin.py
+++ b/morphlib/plugins/branch_and_merge_plugin.py
@@ -54,7 +54,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
 
         # Advanced commands
         self.app.add_subcommand('foreach', self.foreach,
-                                arg_synopsis='COMMAND')
+                                arg_synopsis='-- COMMAND')
 
         # Plumbing commands (FIXME: should be hidden from --help by default)
         self.app.add_subcommand('workspace', self.workspace,
@@ -505,7 +505,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
         self.app.status(msg='Initialized morph workspace', chatty=True)
 
     def branch(self, args):
-        '''Branch the whole system.'''
+        '''Create a new system branch.'''
 
         if len(args) not in [2, 3]:
             raise cliapp.AppException('morph branch needs name of branch '
@@ -714,19 +714,18 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              'been comitted')
 
     def petrify(self, args):
-        '''Convert all chunk refs in a branch to be fixed SHA1s
-
-        This allows the developer to work on a feature in isolation, without
-        changes from upstream breaking the world under their feet.
-
-        Strata refs are not petrified, because they must all be edited to set
-        the new chunk refs, which requires branching them all for the current
-        branch - so they will not be updated outside of the user's control in
-        any case. Chunks that have already been edited on the current branch
-        are also not petrified.
+        '''Convert all chunk refs in a system branch to be fixed SHA1s
 
+        This isolates the branch from changes made by other developers in the
+        chunk repositories.
         '''
 
+        # Stratum refs are not petrified, because they must all be edited to
+        # set the new chunk refs, which requires branching them all for the
+        # current branch - so they will not be updated outside of the user's
+        # control in any case. Chunks that have already been edited on the
+        # current branch are also not petrified.
+
         if len(args) != 0:
             raise cliapp.AppException('morph petrify takes no arguments')
 
@@ -786,16 +785,10 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              'been comitted')
 
     def unpetrify(self, args):
-        '''Reverse the process of petrification
-
-        Unpetrifies all chunk refs in a branch that were previously petrified.
-        Makes no attempt to 'unedit' strata that were branched solely so they
-        could be petrified.
-
-        If a branch is petrified and then branched from, the child branch can
-        be unpetrified independently of the parent.
+        '''Reverse the process of petrification'''
 
-        '''
+        # This function makes no attempt to 'unedit' strata that were branched
+        # solely so they could be petrified.
 
         if len(args) != 0:
             raise cliapp.AppException('morph unpetrify takes no arguments')
@@ -1115,6 +1108,8 @@ class BranchAndMergePlugin(cliapp.Plugin):
             raise
 
     def build(self, args):
+        '''Build a system from the current system branch'''
+
         if len(args) != 1:
             raise cliapp.AppException('morph build expects exactly one '
                                       'parameter: the system to build')
@@ -1334,6 +1329,7 @@ class BranchAndMergePlugin(cliapp.Plugin):
                              ':%s' % info['build-ref']], cwd=info['dirname'])
 
     def status(self, args):
+        '''Show information about the current system branch or workspace'''
         if len(args) != 0:
             raise cliapp.AppException('morph status takes no arguments')
 
@@ -1379,16 +1375,14 @@ class BranchAndMergePlugin(cliapp.Plugin):
     def foreach(self, args):
         '''Run a command in each repository checked out in a system branch
 
-        For simplicity, this simply iterates repositories in the directory
-        rather than walking through the morphologies as 'morph merge' does.
-
-        Morph will interpret switch arguments, so you should separate the
-        command with --, as in the following example:
-
-            morph foreach -- git status --short
+        Use -- before specifying the command to separate its arguments from
+        Morph's own arguments.
 
         '''
 
+        # For simplicity, this simply iterates repositories in the directory
+        # rather than walking through the morphologies as 'morph merge' does.
+
         if len(args) == 0:
             raise cliapp.AppException('morph foreach expects a command to run')
 
@@ -1416,18 +1410,18 @@ class BranchAndMergePlugin(cliapp.Plugin):
                     'Command failed at repo %s: %s' % (repo, ' '.join(args)))
 
     def workspace(self, args):
-        '''Find morph workspace directory from current working directory.'''
+        '''Find the toplevel directory of the current workspace'''
 
         self.app.output.write('%s\n' % self.deduce_workspace())
 
     def show_system_branch(self, args):
-        '''Print name of current system branch.'''
+        '''Print name of current system branch'''
 
         branch, dirname = self.deduce_system_branch()
         self.app.output.write('%s\n' % branch)
 
     def show_branch_root(self, args):
-        '''Print name of the repository that was branched off from.'''
+        '''Print name of the repository holding the system morphologies'''
 
         workspace = self.deduce_workspace()
         system_branch, branch_dir = self.deduce_system_branch()
diff --git a/morphlib/plugins/build_plugin.py b/morphlib/plugins/build_plugin.py
index 7cc2d6ec..6583a6a8 100644
--- a/morphlib/plugins/build_plugin.py
+++ b/morphlib/plugins/build_plugin.py
@@ -29,15 +29,10 @@ class BuildPlugin(cliapp.Plugin):
         pass
 
     def build_morphology(self, args):
-        '''Build a binary from a morphology.
+        '''Build a system, outside of a system branch
 
-        Command line arguments are the repository, git tree-ish reference,
-        and morphology filename. Morph takes care of building all dependencies
-        before building the morphology. All generated binaries are put into the
-        cache.
-
-        (The triplet of command line arguments may be repeated as many
-        times as necessary.)
+        Command line arguments are the repository, git ref,
+        and morphology filename.
 
         '''
 
diff --git a/morphlib/plugins/graphing_plugin.py b/morphlib/plugins/graphing_plugin.py
index 3594e9b9..c719f6e4 100644
--- a/morphlib/plugins/graphing_plugin.py
+++ b/morphlib/plugins/graphing_plugin.py
@@ -31,6 +31,7 @@ class GraphingPlugin(cliapp.Plugin):
         pass
 
     def graph_build_depends(self, args):
+        '''Create a visualisation of build dependencies in a stratum'''
         for repo_name, ref, filename in self.app.itertriplets(args):
             self.app.status(msg='Creating build order for '
                                 '%(repo_name)s %(ref)s %(filename)s',
diff --git a/morphlib/plugins/hello_plugin.py b/morphlib/plugins/hello_plugin.py
deleted file mode 100644
index 85fbdf28..00000000
--- a/morphlib/plugins/hello_plugin.py
+++ /dev/null
@@ -1,29 +0,0 @@
-# Copyright (C) 2012  Codethink Limited
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; version 2 of the License.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License along
-# with this program; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-
-
-import cliapp
-
-
-class Hello(cliapp.Plugin):
-
-    def enable(self):
-        self.app.add_subcommand('hello', self.hello, arg_synopsis='')
-
-    def disable(self):
-        pass
-
-    def hello(self, args):
-        self.app.output.write('hello, world\n')
diff --git a/morphlib/plugins/show_dependencies_plugin.py b/morphlib/plugins/show_dependencies_plugin.py
index dee84c59..13ec512a 100644
--- a/morphlib/plugins/show_dependencies_plugin.py
+++ b/morphlib/plugins/show_dependencies_plugin.py
@@ -31,7 +31,7 @@ class ShowDependenciesPlugin(cliapp.Plugin):
         pass
 
     def show_dependencies(self, args):
-        '''Dumps the dependency tree of all input morphologies.'''
+        '''Dumps the dependency tree of all input morphologies'''
 
         if not os.path.exists(self.app.settings['cachedir']):
             os.mkdir(self.app.settings['cachedir'])
diff --git a/morphlib/plugins/syslinux-disk-systembuilder_plugin.py b/morphlib/plugins/syslinux-disk-systembuilder_plugin.py
index cd734e29..cc47389c 100644
--- a/morphlib/plugins/syslinux-disk-systembuilder_plugin.py
+++ b/morphlib/plugins/syslinux-disk-systembuilder_plugin.py
@@ -91,7 +91,8 @@ class SyslinuxDiskBuilderPlugin(cliapp.Plugin):
                 ['syslinux-mbr-search-paths'],
                 'A list of files to search for to use as the syslinux mbr',
                 default=['/usr/lib/extlinux/mbr.bin',
-                         '/usr/share/syslinux/mbr.bin'])
+                         '/usr/share/syslinux/mbr.bin'],
+                group='Build Options')
             self.app.system_kind_builder_factory.register(SyslinuxDiskBuilder)
 
     def disable(self):
diff --git a/morphlib/plugins/update_gits_plugin.py b/morphlib/plugins/update_gits_plugin.py
index 608b34f1..083439f5 100644
--- a/morphlib/plugins/update_gits_plugin.py
+++ b/morphlib/plugins/update_gits_plugin.py
@@ -31,13 +31,7 @@ class UpdateGitsPlugin(cliapp.Plugin):
         pass
 
     def update_gits(self, args):
-        '''Update cached git repositories.
-
-        Parse the given morphologies, and their dependencies, and
-        update all the git repositories referred to by them in the
-        morph cache directory.
-
-        '''
+        '''Manually update cached git repositories for the given morphology'''
 
         app = self.app
         if not os.path.exists(app.settings['cachedir']):