Add documentation for new ansible-galaxy role options in 1.8. Much rejoicing.

docsite/rst/galaxy.rst

@@ -1,10 +1,89 @@
 Ansible Galaxy
 ``````````````
 
-`Ansible Galaxy <http://galaxy.ansible.com>`_, is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
+"Ansible Galaxy" can either refer to a website for sharing and downloading Ansible roles, or a command line tool that helps work with roles.
 
-You can sign up with social auth, and the download client 'ansible-galaxy' is included in Ansible 1.4.2 and later.
+The Website
+```````````
+
+The website `Ansible Galaxy <http://galaxy.ansible.com>`_, is a free site for finding, downloading, rating, and reviewing all kinds of community developed Ansible roles and can be a great way to get a jumpstart on your automation projects.
+
+You can sign up with social auth, and use the download client 'ansible-galaxy' is included in Ansible 1.4.2 and later.
 
 Read the "About" page on the Galaxy site for more information.
 
+The ansible-galaxy command line tool
+````````````````````````````````````
+
+The command line ansible-galaxy has many different subcommands.
+
+Installing Roles
+++++++++++++++++
+
+The most obvious is downloading roles from the Ansible Galaxy website::
+
+   ansible-galaxy install username.rolename
+
+Building out Role Scaffolding
++++++++++++++++++++++++++++++
+
+It can also be used to initialize the base structure of a new role, saving time on creating the various directories and main.yml files a role requires::
+
+   ansible-galaxy init rolename
+
+Installing Multiple Roles From A File
++++++++++++++++++++++++++++++++++++++
+
+To install multiple roles, the ansible-galaxy CLI can be fed a requirements file.  All versions of ansible allow the following syntax for installing roles from the Ansible Galaxy website::
+
+   ansible-galaxy install -r requirements.txt
+
+Where the requirements.txt looks like::
+
+   username1.foo_role
+   username2.bar_role
+
+To request specific versions (tags) of a role, use this syntax in the roles file::
+
+   username1.foo_role,version
+   username2.bar_role,version
+
+Available versions will be listed on the Ansible Galaxy webpage for that role.
+
+Advanced Control over Role Requirements Files
++++++++++++++++++++++++++++++++++++++++++++++
+
+For more advanced control over where to download roles from, including support for remote repositories, Ansible 1.8 and later support a new YAML format for the role requirements file, which must end in a 'yml' extension.  It works like this::
+
+    ansible-galaxy install -r requirements.yml
+
+The extension is important. If the .yml extension is left off, the ansible-galaxy CLI will assume the file is in the "basic" format and will be confused.
+
+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: git+http://bitbucket.org/willthames/git-ansible-galaxy
+      version: v1.4
+
+    - src: http://bitbucket.org/willthames/hg-ansible-galaxy
+      scm: hg
+
+    - src: https://bitbucket.org/willthames/http-ansible-galaxy/get/master.tar.g      name: http-role
+
+    - galaxyusername.rolename
+      version: v1.5
+      name: save_as_this_role_name
+
+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.     
+
+Roles pulled from galaxy work as with othe SCM sourced roles above. To download a role with dependencies, and automatically install those dependencies, the role must be uploaded to the Ansible Galaxy website.
+
+.. seealso::
+
+   :doc:`playbooks_roles`
+       All about ansible roles
+   `Mailing List <http://groups.google.com/group/ansible-project>`_
+       Questions? Help? Ideas?  Stop by the list on Google Groups
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
 

docsite/rst/playbooks_roles.rst

@@ -386,6 +386,8 @@ Read the "About" page on the Galaxy site for more information.
 
 .. seealso::
 
+   :doc:`galaxy`
+       How to share roles on galaxy, role management
    :doc:`YAMLSyntax`
        Learn about YAML syntax
    :doc:`playbooks`