Clarify examples further.

2 files changed, 64 insertions, 53 deletions

diff --git a/bin/ansible-galaxy b/bin/ansible-galaxy
index 0a51a4b63e..801c4a53f9 100755
--- a/bin/ansible-galaxy
+++ b/bin/ansible-galaxy
@@ -234,7 +234,7 @@ def exit_without_ignore(options, rc=1):
     """
 
     if not get_opt(options, "ignore_errors", False):
-        print 'You can use --ignore-errors to skip failed roles.'
+        print '- you can use --ignore-errors to skip failed roles.'
         sys.exit(rc)
 
 #-------------------------------------------------------------------------------------
@@ -268,10 +268,10 @@ def api_lookup_role_by_name(api_server, role_name):
         parts = role_name.split(".")
         user_name = ".".join(parts[0:-1])
         role_name = parts[-1]
-        print " downloading role '%s', owned by %s" % (role_name, user_name)
+        print "- downloading role '%s', owned by %s" % (role_name, user_name)
     except:
         parser.print_help()
-        print "Invalid role name (%s). You must specify username.rolename" % role_name
+        print "- invalid role name (%s). Specify role as format: username.rolename" % role_name
         sys.exit(1)
 
     url = 'https://%s/api/v1/roles/?owner__username=%s&name=%s' % (api_server,user_name,role_name)
@@ -329,7 +329,7 @@ def api_get_list(api_server, what):
             done = (data.get('next', None) == None)
         return results
     except:
-        print " - failed to download the %s list" % what
+        print "- failed to download the %s list" % what
         return None
 
 #-------------------------------------------------------------------------------------
@@ -338,7 +338,7 @@ def api_get_list(api_server, what):
 
 def scm_archive_role(scm, role_url, role_version, role_name):
     if scm not in ['hg', 'git']:
-        print "SCM %s is not currently supported" % scm
+        print "- scm %s is not currently supported" % scm
         return False
     tempdir = tempfile.mkdtemp()
     clone_cmd = [scm, 'clone', role_url, role_name]
@@ -476,7 +476,7 @@ def fetch_role(role_name, target, role_data, options):
         archive_url = role_name
     else: 
         archive_url = 'https://github.com/%s/%s/archive/%s.tar.gz' % (role_data["github_user"], role_data["github_repo"], target)
-    print " - downloading role from %s" % archive_url
+    print "- downloading role from %s" % archive_url
 
     try:
         url_file = urllib2.urlopen(archive_url)
@@ -490,7 +490,7 @@ def fetch_role(role_name, target, role_data, options):
     except Exception, e:
         # TODO: better urllib2 error handling for error 
         #       messages that are more exact
-        print "Error: failed to download the file."
+        print "- error: failed to download the file."
         return False
 
 def install_role(role_name, role_version, role_filename, options):
@@ -498,7 +498,7 @@ def install_role(role_name, role_version, role_filename, options):
     # to the specified (or default) roles directory
 
     if not tarfile.is_tarfile(role_filename):
-        print "Error: the file downloaded was not a tar.gz"
+        print "- error: the file downloaded was not a tar.gz"
         return False
     else:
         if role_filename.endswith('.gz'):
@@ -514,13 +514,13 @@ def install_role(role_name, role_version, role_filename, options):
                 meta_file = member
                 break
         if not meta_file:
-            print "Error: this role does not appear to have a meta/main.yml file."
+            print "- error: this role does not appear to have a meta/main.yml file."
             return False
         else:
             try:
                 meta_file_data = yaml.safe_load(role_tar_file.extractfile(meta_file))
             except:
-                print "Error: this role does not appear to have a valid meta/main.yml file."
+                print "- error: this role does not appear to have a valid meta/main.yml file."
                 return False
 
         # we strip off the top-level directory for all of the files contained within
@@ -528,20 +528,20 @@ def install_role(role_name, role_version, role_filename, options):
         # to the specified role's name
         role_path = os.path.join(get_opt(options, 'roles_path', '/etc/ansible/roles'), role_name)
         role_path = os.path.expanduser(role_path)
-        print " - extracting %s to %s" % (role_name, role_path)
+        print "- extracting %s to %s" % (role_name, role_path)
         try:
             if os.path.exists(role_path):
                 if not os.path.isdir(role_path):
-                    print "Error: the specified roles path exists and is not a directory."
+                    print "- error: the specified roles path exists and is not a directory."
                     return False
                 elif not get_opt(options, "force", False):
-                    print "Error: the specified role %s appears to already exist. Use --force to replace it." % role_name
+                    print "- error: the specified role %s appears to already exist. Use --force to replace it." % role_name
                     return False
                 else:
                     # using --force, remove the old path
                     if not remove_role(role_name, options):
-                        print "Error: %s doesn't appear to contain a role." % role_path
-                        print "Please remove this directory manually if you really want to put the role here."
+                        print "- error: %s doesn't appear to contain a role." % role_path
+                        print "  please remove this directory manually if you really want to put the role here."
                         return False
             else:
                 os.makedirs(role_path)
@@ -563,11 +563,11 @@ def install_role(role_name, role_version, role_filename, options):
             # write out the install info file for later use
             write_galaxy_install_info(role_name, role_version, options)
         except OSError, e:
-            print "Error: you do not have permission to modify files in %s" % role_path
+            print "- error: you do not have permission to modify files in %s" % role_path
             return False
 
         # return the parsed yaml metadata
-        print "%s was installed successfully" % role_name
+        print "- %s was installed successfully" % role_name
         return meta_file_data
 
 #-------------------------------------------------------------------------------------
@@ -588,7 +588,7 @@ def execute_init(args, options, parser):
     if not offline:
         api_config = api_get_config(api_server)
         if not api_config:
-            print "The API server (%s) is not responding, please try again later." % api_server
+            print "- the API server (%s) is not responding, please try again later." % api_server
             sys.exit(1)
 
     try:
@@ -598,18 +598,17 @@ def execute_init(args, options, parser):
         role_path = os.path.join(init_path, role_name)
         if os.path.exists(role_path):
             if os.path.isfile(role_path):
-                print "The path %s already exists, but is a file - aborting" % role_path
+                print "- the path %s already exists, but is a file - aborting" % role_path
                 sys.exit(1)
             elif not force:
-                print "The directory %s already exists." % role_path
-                print ""
-                print "You can use --force to re-initialize this directory,\n" + \
-                      "however it will reset any main.yml files that may have\n" + \
-                      "been modified there already."
+                print "- the directory %s already exists." % role_path
+                print "  you can use --force to re-initialize this directory,\n" + \
+                      "  however it will reset any main.yml files that may have\n" + \
+                      "  been modified there already."
                 sys.exit(1)
     except Exception, e:
         parser.print_help()
-        print "No role name specified for init"
+        print "- no role name specified for init"
         sys.exit(1)
 
     ROLE_DIRS = ('defaults','files','handlers','meta','tasks','templates','vars')
@@ -668,7 +667,7 @@ def execute_init(args, options, parser):
             f = open(main_yml_path, 'w')
             f.write('---\n# %s file for %s\n' % (dir,role_name))
             f.close()
-    print "%s was created successfully" % role_name
+    print "- %s was created successfully" % role_name
 
 def execute_info(args, options, parser):
     """
@@ -695,13 +694,13 @@ def execute_install(args, options, parser):
         # the user needs to specify one of either --role-file
         # or specify a single user/role name
         parser.print_help()
-        print "You must specify a user/role name or a roles file"
+        print "- you must specify a user/role name or a roles file"
         sys.exit()
     elif len(args) == 1 and role_file:
         # using a role file is mutually exclusive of specifying
         # the role name on the command line
         parser.print_help()
-        print "Please specify a user/role name, or a roles file, but not both"
+        print "- please specify a user/role name, or a roles file, but not both"
         sys.exit(1)
 
     roles_done = []
@@ -739,12 +738,12 @@ def execute_install(args, options, parser):
                 # installing from galaxy
                 api_config = api_get_config(api_server)
                 if not api_config:
-                    print "The API server (%s) is not responding, please try again later." % api_server
+                    print "- the API server (%s) is not responding, please try again later." % api_server
                     sys.exit(1)
 
                 role_data = api_lookup_role_by_name(api_server, role_src)
                 if not role_data:
-                    print "Sorry, %s was not found on %s." % (role_src, api_server)
+                    print "- sorry, %s was not found on %s." % (role_src, api_server)
                     continue
 
                 role_versions = api_fetch_role_related(api_server, 'versions', role_data['id'])
@@ -761,14 +760,16 @@ def execute_install(args, options, parser):
                         role["version"] = 'master'
                 else:
                     if role_versions and role["version"] not in [a.get('name',None) for a in role_versions]:
-                        print "The specified version (%s) was not found in the list of available versions." % role.version
+                        print "- the specified version (%s) was not found in the list of available versions." % role.version
                         exit_without_ignore(options)
                         continue
 
                 # download the role. if --no-deps was specified, we stop here, 
                 # otherwise we recursively grab roles and all of their deps.
                 tmp_file = fetch_role(role_src, role["version"], role_data, options)
-        if tmp_file and install_role(role.get("name"), role.get("version"), tmp_file, options):
+        installed = False
+        if tmp_file:
+            installed = install_role(role.get("name"), role.get("version"), tmp_file, options):
             # we're done with the temp file, clean it up
             os.unlink(tmp_file)
             # install dependencies, if we want them
@@ -784,14 +785,14 @@ def execute_install(args, options, parser):
                     else:
                         dep = ansible.utils.role_yaml_parse(dep)
                     if not get_role_metadata(dep["name"], options):
-                        print ' adding dependency: %s' % dep["name"]
+                        print '- adding dependency: %s' % dep["name"]
                         roles_left.append(dep)
                     else:
-                        print ' dependency %s is already installed, skipping.' % dep["name"]
-        else:
+                        print '- dependency %s is already installed, skipping.' % dep["name"]
+        if not tmp_file or not installed:
             if tmp_file:
                 os.unlink(tmp_file)
-            print "%s was NOT installed successfully." % role.get("name")
+            print "- %s was NOT installed successfully." % role.get("name")
             exit_without_ignore(options)
     sys.exit(0)
 
@@ -803,17 +804,17 @@ def execute_remove(args, options, parser):
 
     if len(args) == 0:
         parser.print_help()
-        print 'You must specify at least one role to remove.'
+        print '- you must specify at least one role to remove.'
         sys.exit()
 
     for role in args:
         if get_role_metadata(role, options):
             if remove_role(role, options):
-                print 'successfully removed %s' % role
+                print '- successfully removed %s' % role
             else:
-                print "failed to remove role: %s" % role
+                print "- failed to remove role: %s" % role
         else:
-            print '%s is not installed, skipping.' % role
+            print '- %s is not installed, skipping.' % role
     sys.exit(0)
 
 def execute_list(args, options, parser):
@@ -825,7 +826,7 @@ def execute_list(args, options, parser):
     """
 
     if len(args) > 1:
-        print "Please specify only one role to list, or specify no roles to see a full list"
+        print "- please specify only one role to list, or specify no roles to see a full list"
         sys.exit(1)
 
     if len(args) == 1:
@@ -840,19 +841,19 @@ def execute_list(args, options, parser):
             if not version:
                 version = "(unknown version)"
             # show some more info about single roles here
-            print " %s, %s" % (role_name, version)
+            print "- %s, %s" % (role_name, version)
         else:
-            print "The role %s was not found" % role_name
+            print "- the role %s was not found" % role_name
     else:
         # show all valid roles in the roles_path directory
         roles_path = get_opt(options, 'roles_path')
         roles_path = os.path.expanduser(roles_path)
         if not os.path.exists(roles_path):
             parser.print_help()
-            print "The path %s does not exist. Please specify a valid path with --roles-path" % roles_path
+            print "- the path %s does not exist. Please specify a valid path with --roles-path" % roles_path
             sys.exit(1)
         elif not os.path.isdir(roles_path):
-            print "%s exists, but it is not a directory. Please specify a valid path with --roles-path" % roles_path
+            print "- %s exists, but it is not a directory. Please specify a valid path with --roles-path" % roles_path
             parser.print_help()
             sys.exit(1)
         path_files = os.listdir(roles_path)
@@ -864,7 +865,7 @@ def execute_list(args, options, parser):
                     version = install_info.get("version", None)
                 if not version:
                     version = "(unknown version)"
-                print " %s, %s" % (path_file, version)
+                print "- %s, %s" % (path_file, version)
     sys.exit(0)
 
 #-------------------------------------------------------------------------------------
@@ -882,7 +883,7 @@ def main():
         fn = globals()["execute_%s" % action]
         fn(args, options, parser)
     #except KeyError, e:
-    #    print "Error: %s is not a valid action. Valid actions are: %s" % (action, ", ".join(VALID_ACTIONS))
+    #    print "- error: %s is not a valid action. Valid actions are: %s" % (action, ", ".join(VALID_ACTIONS))
     #    sys.exit(1)
 
 if __name__ == "__main__":
diff --git a/docsite/rst/galaxy.rst b/docsite/rst/galaxy.rst
index 149a98a915..9e3dc3328a 100644
--- a/docsite/rst/galaxy.rst
+++ b/docsite/rst/galaxy.rst
@@ -61,18 +61,28 @@ The extension is important. If the .yml extension is left off, the ansible-galax
 
 And here's an example showing some specific version downloads from multiple sources.  In one of the examples we also override the name of the role and download it as something different::
 
-    - src: bennojoy.mysql
-      name: mysql # save as mysql not bennojoy.mysql
- 
+    # from galaxy
+    - src: yatesr.timezone
+
+    # from github
+    - src: https://github.com/bennojoy/nginx
+
+    # from github, overriding the name and specifying a specific tag
+    - src: https://github.com/bennojoy/nginx
+      name: nginx_role
+    
+    # from a webserver, where the role is packaged in a tar.gz
+    - src: https://some.webserver.example.com/files/master.tar.gz
+      name: http-role
+
+    # from bitbucket, if bitbucket happens to be operational right now :)
     - src: git+http://bitbucket.org/willthames/git-ansible-galaxy
       version: v1.4
 
+    # from bitbucket, alternative syntax and caveats
     - src: http://bitbucket.org/willthames/hg-ansible-galaxy
       scm: hg
 
-    - src: https://bitbucket.org/willthames/http-ansible-galaxy/get/master.tar.gz
-      name: http-role
-
 As you can see in the above, there are a large amount of controls available
 to customize where roles can be pulled from, and what to save roles as.