Merge lp:~mthaddon/codetree/help-more-helpful into lp:codetree

[Tom Haddon]

Move details of configuration format into --help command to make it more user-accessible

[lp:~mthaddon/codetree/help-more-helpful]

124. By Tom Haddon on 2021-02-05

Minor formatting update

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

This merge proposal is being monitored by mergebot. Change the status to Approved to merge.

[Haw Loeung (hloeung)]

LGTM

review: Approve (+1)

[🤖 Canonical IS Merge Bot (canonical-is-mergebot)]

Change successfully merged at revision 124

=== modified file 'README.md'
--- README.md	2021-02-05 09:12:52 +0000
+++ README.md	2021-02-05 09:41:32 +0000
@@ -13,36 +13,7 @@
 
 [Config-manager](https://launchpad.net/config-manager) configuration files should be compatible with codetree. Codetree has a few more features, and therefore some additional config syntax.
 
-Configuration files consist of directives, one per line, consisting of a local destination and a source. Blank lines and lines whose first character is "#" are ignored.
-
-Here's an example config:
-
-    app                     lp:myapp;lightweight=true
-    app/plugins/woohoo      lp:myapp-woohoo;revno=44
-    app/images/logo.gif     http://content.internal/myimage.gif;overwrite=true
-    app/downloads           @
-    app/content             /home/contentbot/appcontent;method=link
-    app/mytag               git://github.com/myapp;revno=mytag
-    app2                    git+ssh://[e-mail]/me/app2.git
-    app3                    git+https://github.com/me/my3rdapp.git
-    app4                    git+lp:~owner/project/+git/branch
-    app5                    git+lp:~owner/project;revno=mytag
-    mycharm                 cs:trusty/mycharm
-    othercharm              cs:trusty/othercharm;channel=edge,overwrite=true
-
-Taking that line-by-line:
-
-* the app directory contains a copy of the latest version of myapp, a bzr repo hosted on launchpad.net. Since "lightweight" is specified a lightweight checkout will be used rather than the default branching behavior.
-* the app/plugins/woohoo directory contains revision number 44 of lp:myapp-woohoo
-* app/image/logo.gif is a single image file. If it exists it will be overwritten.
-* app/downloads is an empty directory
-* app/content is a symlink of the local directory /home/contentbot/appcontent.
-* app/mytag is a git checkout of the git repository from github at the tag 'mytag'
-* app2 is also a git checkout but using a different format for the git url
-* app3 is another git checkout but using the https style git url understood by codetree
-* app4 is a git checkout from ssh://git.launchpad.net/~owner/project/+git/branch
-* app5 is a git checkout of the mytag branch from ssh://git.launchpad.net/~owner/project/+git/project (if the project and repository name match, Launchpad allows it to be shortened in this way).
-* mycharm is a Juju charm from the [charm store](https://jujucharms.com/)
+See `codetree --help` for details of the configuration file format.
 
 ### Source URLs
 

=== modified file 'codetree/cli.py'
--- codetree/cli.py	2020-01-30 22:08:26 +0000
+++ codetree/cli.py	2021-02-05 09:41:32 +0000
@@ -1,13 +1,51 @@
 from __future__ import division, print_function
-from argparse import ArgumentParser
+from argparse import ArgumentParser, RawTextHelpFormatter
 import logging
 from .config import Config
 import sys
 
 
 def main():
-    ap = ArgumentParser()
-    ap.add_argument("cfgfile", nargs="+", help="Codetree configuration file")
+    ap = ArgumentParser(formatter_class=RawTextHelpFormatter)
+    cfgfile_help = """Codetree configuration file.
+
+Configuration files consist of directives, one per line, consisting of a local
+destination and a source. Blank lines and lines whose first character is "#"
+are ignored.
+
+Here's an example config:
+
+    app                     lp:myapp;lightweight=true
+    app/plugins/woohoo      lp:myapp-woohoo;revno=44
+    app/images/logo.gif     http://content.internal/myimage.gif;overwrite=true
+    app/downloads           @
+    app/content             /home/contentbot/appcontent;method=link
+    app/mytag               git://github.com/myapp;revno=mytag
+    app2                    git+ssh://[e-mail]/me/app2.git
+    app3                    git+https://github.com/me/my3rdapp.git
+    app4                    git+lp:~owner/project/+git/branch
+    app5                    git+lp:~owner/project;revno=mytag
+    mycharm                 cs:trusty/mycharm
+    othercharm              cs:trusty/othercharm;channel=edge,overwrite=true
+
+Taking that line-by-line:
+
+* the app directory contains a copy of the latest version of myapp, a bzr repo hosted
+  on launchpad.net. Since "lightweight" is specified a lightweight checkout will be
+  used rather than the default branching behavior.
+* the app/plugins/woohoo directory contains revision number 44 of lp:myapp-woohoo.
+* app/image/logo.gif is a single image file. If it exists it will be overwritten.
+* app/downloads is an empty directory.
+* app/content is a symlink of the local directory /home/contentbot/appcontent.
+* app/mytag is a git checkout of the git repository from github at the tag 'mytag'.
+* app2 is also a git checkout but using a different format for the git url.
+* app3 is another git checkout but using the https style git url understood by codetree.
+* app4 is a git checkout from ssh://git.launchpad.net/~owner/project/+git/branch.
+* app5 is a git checkout of the mytag branch from
+  ssh://git.launchpad.net/~owner/project/+git/project (if the project and repository
+  name match, Launchpad allows it to be shortened in this way).
+* mycharm is a Juju charm from the [charm store](https://jujucharms.com/)."""
+    ap.add_argument("cfgfile", nargs="+", help=cfgfile_help)
     ap.add_argument("-d", "--dry-run", action="store_true", default=False)
     verbosity = ap.add_mutually_exclusive_group(required=False)
     verbosity.add_argument("-v", "--verbose", action="store_true", default=False)