From ba4fbd2b66104fb1622d4d5e66369a8a750f9363 Mon Sep 17 00:00:00 2001 From: James Cammarata Date: Sun, 16 Mar 2014 13:58:42 -0500 Subject: [PATCH] Adding man page for ansible-galaxy Partially resolves #6471 --- Makefile | 3 +- docs/man/man1/ansible-galaxy.1 | 180 +++++++++++++++++++++ docs/man/man1/ansible-galaxy.1.asciidoc.in | 167 +++++++++++++++++++ 3 files changed, 349 insertions(+), 1 deletion(-) create mode 100644 docs/man/man1/ansible-galaxy.1 create mode 100644 docs/man/man1/ansible-galaxy.1.asciidoc.in diff --git a/Makefile b/Makefile index 982cd143b2..41d80a13c3 100644 --- a/Makefile +++ b/Makefile @@ -20,7 +20,7 @@ OS = $(shell uname -s) # Manpages are currently built with asciidoc -- would like to move to markdown # This doesn't evaluate until it's called. The -D argument is the # directory of the target file ($@), kinda like `dirname`. -MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 +MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 docs/man/man1/ansible-galaxy.1 ifneq ($(shell which a2x 2>/dev/null),) ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $< ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml @@ -172,3 +172,4 @@ deb: debian webdocs: $(MANPAGES) (cd docsite/; make docs) +docs: $(MANPAGES) diff --git a/docs/man/man1/ansible-galaxy.1 b/docs/man/man1/ansible-galaxy.1 new file mode 100644 index 0000000000..af2285121a --- /dev/null +++ b/docs/man/man1/ansible-galaxy.1 @@ -0,0 +1,180 @@ +'\" t +.\" Title: ansible-galaxy +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.78.1 +.\" Date: 03/16/2014 +.\" Manual: System administration commands +.\" Source: Ansible 1.6 +.\" Language: English +.\" +.TH "ANSIBLE\-GALAXY" "1" "03/16/2014" "Ansible 1\&.6" "System administration commands" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ansible-galaxy \- manage roles using galaxy\&.ansible\&.com +.SH "SYNOPSIS" +.sp +ansible\-galaxy [init|info|install|list|remove] [\-\-help] [options] \&... +.SH "DESCRIPTION" +.sp +\fBAnsible Galaxy\fR is a shared repository for Ansible roles (added in ansible version 1\&.2)\&. The ansible\-galaxy command can be used to manage these roles, or by creating a skeleton framework for roles you\(cqd like to upload to Galaxy\&. +.SH "COMMON OPTIONS" +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show a help message related to the given sub\-command\&. +.RE +.SH "INSTALL" +.sp +The \fBinstall\fR sub\-command is used to install roles\&. +.SS "USAGE" +.sp +$ ansible\-galaxy install [options] [\-r FILE | role_name(s)[,version] | tar_file(s)] +.sp +Roles can be installed in several different ways: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A username\&.rolename[,version] \- this will install a single role\&. The Galaxy API will be contacted to provide the information about the role, and the corresponding \&.tar\&.gz will be downloaded from +\fBgithub\&.com\fR\&. If the version is omitted, the most recent version available will be installed\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A file name, using +\fB\-r\fR +\- this will install multiple roles listed one per line\&. The format of each line is the same as above: username\&.rolename[,version] +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A \&.tar\&.gz of a valid role you\(cqve downloaded directly from +\fBgithub\&.com\fR\&. This is mainly useful when the system running Ansible does not have access to the Galaxy API, for instance when behind a firewall or proxy\&. +.RE +.SS "OPTIONS" +.PP +\fB\-f\fR, \fB\-\-force\fR +.RS 4 +Force overwriting an existing role\&. +.RE +.PP +\fB\-i\fR, \fB\-\-ignore\-errors\fR +.RS 4 +Ignore errors and continue with the next specified role\&. +.RE +.PP +\fB\-n\fR, \fB\-\-no\-deps\fR +.RS 4 +Don\(cqt download roles listed as dependencies\&. +.RE +.PP +\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR +.RS 4 +The path to the directory containing your roles\&. The default is the +\fBroles_path\fR +configured in your +\fBansible\&.cfg\fR +file (/etc/ansible/roles if not configured) +.RE +.PP +\fB\-r\fR \fIROLE_FILE\fR, \fB\-\-role\-file=\fR\fIROLE_FILE\fR +.RS 4 +A file containing a list of roles to be imported, as specified above\&. This option cannot be used if a rolename or \&.tar\&.gz have been specified\&. +.RE +.SH "REMOVE" +.sp +The \fBremove\fR sub\-command is used to remove one or more roles\&. +.SS "USAGE" +.sp +$ ansible\-galaxy remove role1 role2 \&... +.SS "OPTIONS" +.PP +\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR +.RS 4 +The path to the directory containing your roles\&. The default is the +\fBroles_path\fR +configured in your +\fBansible\&.cfg\fR +file (/etc/ansible/roles if not configured) +.RE +.SH "INIT" +.sp +The \fBinit\fR command is used to create an empty role suitable for uploading to https://galaxy\&.ansible\&.com (or for roles in general)\&. +.SS "USAGE" +.sp +$ ansible\-galaxy init [options] role_name +.SS "OPTIONS" +.PP +\fB\-f\fR, \fB\-\-force\fR +.RS 4 +Force overwriting an existing role\&. +.RE +.PP +\fB\-p\fR \fIINIT_PATH\fR, \fB\-\-init\-path=\fR\fIINIT_PATH\fR +.RS 4 +The path in which the skeleton role will be created\&.The default is the current working directory\&. +.RE +.SH "LIST" +.sp +The \fBlist\fR sub\-command is used to show what roles are currently instaled\&. You can specify a role name, and if installed only that role will be shown\&. +.SS "USAGE" +.sp +$ ansible\-galaxy list [role_name] +.SS "OPTIONS" +.PP +\fB\-p\fR \fIROLES_PATH\fR, \fB\-\-roles\-path=\fR\fIROLES_PATH\fR +.RS 4 +The path to the directory containing your roles\&. The default is the +\fBroles_path\fR +configured in your +\fBansible\&.cfg\fR +file (/etc/ansible/roles if not configured) +.RE +.SH "AUTHOR" +.sp +Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&. +.SH "COPYRIGHT" +.sp +Copyright \(co 2014, Michael DeHaan +.sp +Ansible is released under the terms of the GPLv3 License\&. +.SH "SEE ALSO" +.sp +\fBansible\fR(1), \fBansible\-pull\fR(1), \fBansible\-doc\fR(1) +.sp +Extensive documentation is available in the documentation site: http://docs\&.ansible\&.com\&. IRC and mailing list info can be found in file CONTRIBUTING\&.md, available in: https://github\&.com/ansible/ansible diff --git a/docs/man/man1/ansible-galaxy.1.asciidoc.in b/docs/man/man1/ansible-galaxy.1.asciidoc.in new file mode 100644 index 0000000000..b8a80e6b2c --- /dev/null +++ b/docs/man/man1/ansible-galaxy.1.asciidoc.in @@ -0,0 +1,167 @@ +ansible-galaxy(1) +=================== +:doctype: manpage +:man source: Ansible +:man version: %VERSION% +:man manual: System administration commands + +NAME +---- +ansible-galaxy - manage roles using galaxy.ansible.com + + +SYNOPSIS +-------- +ansible-galaxy [init|info|install|list|remove] [--help] [options] ... + + +DESCRIPTION +----------- + +*Ansible Galaxy* is a shared repository for Ansible roles (added in +ansible version 1.2). The ansible-galaxy command can be used to manage +these roles, or by creating a skeleton framework for roles you'd like +to upload to Galaxy. + +COMMON OPTIONS +-------------- + +*-h*, *--help*:: + +Show a help message related to the given sub-command. + + +INSTALL +------- + +The *install* sub-command is used to install roles. + +USAGE +~~~~~ + +$ ansible-galaxy install [options] [-r FILE | role_name(s)[,version] | tar_file(s)] + +Roles can be installed in several different ways: + +* A username.rolename[,version] - this will install a single role. The Galaxy + API will be contacted to provide the information about the role, and the + corresponding .tar.gz will be downloaded from *github.com*. If the version + is omitted, the most recent version available will be installed. + +* A file name, using *-r* - this will install multiple roles listed one per + line. The format of each line is the same as above: username.rolename[,version] + +* A .tar.gz of a valid role you've downloaded directly from *github.com*. This + is mainly useful when the system running Ansible does not have access to + the Galaxy API, for instance when behind a firewall or proxy. + + +OPTIONS +~~~~~~~ + +*-f*, *--force*:: + +Force overwriting an existing role. + +*-i*, *--ignore-errors*:: + +Ignore errors and continue with the next specified role. + +*-n*, *--no-deps*:: + +Don't download roles listed as dependencies. + +*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: + +The path to the directory containing your roles. The default is the *roles_path* +configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) + +*-r* 'ROLE_FILE', *--role-file=*'ROLE_FILE':: + +A file containing a list of roles to be imported, as specified above. This +option cannot be used if a rolename or .tar.gz have been specified. + +REMOVE +------ + +The *remove* sub-command is used to remove one or more roles. + +USAGE +~~~~~ + +$ ansible-galaxy remove role1 role2 ... + +OPTIONS +~~~~~~~ + +*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: + +The path to the directory containing your roles. The default is the *roles_path* +configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) + +INIT +---- + +The *init* command is used to create an empty role suitable for uploading +to https://galaxy.ansible.com (or for roles in general). + +USAGE +~~~~~ + +$ ansible-galaxy init [options] role_name + +OPTIONS +~~~~~~~ + +*-f*, *--force*:: + +Force overwriting an existing role. + +*-p* 'INIT_PATH', *--init-path=*'INIT_PATH':: + +The path in which the skeleton role will be created.The default is the current +working directory. + +LIST +---- + +The *list* sub-command is used to show what roles are currently instaled. +You can specify a role name, and if installed only that role will be shown. + +USAGE +~~~~~ + +$ ansible-galaxy list [role_name] + +OPTIONS +~~~~~~~ + +*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: + +The path to the directory containing your roles. The default is the *roles_path* +configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) + + +AUTHOR +------ + +Ansible was originally written by Michael DeHaan. See the AUTHORS file +for a complete list of contributors. + + +COPYRIGHT +--------- + +Copyright © 2014, Michael DeHaan + +Ansible is released under the terms of the GPLv3 License. + + +SEE ALSO +-------- + +*ansible*(1), *ansible-pull*(1), *ansible-doc*(1) + +Extensive documentation is available in the documentation site: +. IRC and mailing list info can be found +in file CONTRIBUTING.md, available in: