Merge "Add missing docs for zuul-manage-ansible"

doc/source/admin/installation.rst

@@ -101,11 +101,13 @@ Ansible
 ~~~~~~~
 
 Zuul uses Ansible to run jobs.  Each version of Zuul is designed to
-work with a specific, contemporary version of Ansible.  Zuul specifies
-that version of Ansible in its python package metadata, and normally
-the correct version will be installed automatically with Zuul.
-Because of the close integration of Zuul and Ansible, attempting to
-use other versions of Ansible with Zuul is not recommended.
+work with a specific, contemporary versions of Ansible. Zuul manages
+its Ansible installations using ``zuul-manage-ansible``. It is
+recommended to run ``zuul-manage-ansible`` before starting the zuul-executor
+the first time.
+
+.. program-output:: zuul-manage-ansible -h
+
 
 Zuul Setup
 ----------

zuul/cmd/__init__.py

@@ -107,7 +107,9 @@ class ZuulApp(object):
         return "Zuul version: %s" % zuul_version_info.release_string()
 
     def createParser(self):
-        parser = argparse.ArgumentParser(description=self.app_description)
+        parser = argparse.ArgumentParser(
+            description=self.app_description,
+            formatter_class=argparse.RawDescriptionHelpFormatter)
         parser.add_argument('-c', dest='config',
                             help='specify the config file')
         parser.add_argument('--version', dest='version', action='version',

zuul/cmd/manage_ansible.py

@@ -14,6 +14,7 @@
 # under the License.
 
 import logging
+import textwrap
 import zuul.cmd
 from zuul.lib.ansible import AnsibleManager
 
@@ -21,7 +22,26 @@ from zuul.lib.ansible import AnsibleManager
 class ManageAnsible(zuul.cmd.ZuulApp):
 
     app_name = 'manage-ansible'
-    app_description = 'Zuul ansible maager'
+    app_description = textwrap.dedent('''
+        Zuul ansible manager.
+
+        This command installs or upgrades all supported Ansible installations
+        so zuul can use them.
+
+        You can set the following environnment variables
+        to install additional packages you might need along with ansible.
+        These variables must contain a space separated list of dependencies
+        that can be parsed by pip.
+
+        ANSIBLE_EXTRA_PACKAGES
+            Packages to add to every ansible installation.
+
+        ANSIBLE_<VERSION>_EXTRA_PACKAGES
+            Packages to add to a specific version of Ansible. The version must
+            be the same as listed in 'zuul-manage-ansible -l' but without
+            special characters. e.g. ANSIBLE_27_EXTRA_PACKAGES=myextradep
+        ''')
+
     log = logging.getLogger('zuul.ManageAnsible')
 
     def createParser(self):