Merge pull request #2506 from tbielawa/aoi-manpage

Add a manpage for atomic-openshift-installer

3 files changed, 374 insertions, 0 deletions

diff --git a/utils/Makefile b/utils/Makefile
index 79c27626a..078d6f184 100644
--- a/utils/Makefile
+++ b/utils/Makefile
@@ -25,6 +25,12 @@ NAME := oo-install
 TESTPACKAGE := oo-install
 SHORTNAME := ooinstall
 
+# This doesn't evaluate until it's called. The -D argument is the
+# directory of the target file ($@), kinda like `dirname`.
+ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
+MANPAGES := docs/man/man1/atomic-openshift-installer.1
+VERSION := 1.3
+
 sdist: clean
 	python setup.py sdist
 	rm -fR $(SHORTNAME).egg-info
@@ -35,6 +41,21 @@ clean:
 	@rm -fR build dist rpm-build MANIFEST htmlcov .coverage cover ooinstall.egg-info oo-install
 	@rm -fR $(NAME)env
 
+
+# To force a rebuild of the docs run 'touch' on any *.in file under
+# docs/man/man1/
+docs: $(MANPAGES)
+
+# Regenerate %.1.asciidoc if %.1.asciidoc.in has been modified more
+# recently than %.1.asciidoc.
+%.1.asciidoc: %.1.asciidoc.in
+	sed "s/%VERSION%/$(VERSION)/" $< > $@
+
+# Regenerate %.1 if %.1.asciidoc or VERSION has been modified more
+# recently than %.1. (Implicitly runs the %.1.asciidoc recipe)
+%.1: %.1.asciidoc
+	$(ASCII2MAN)
+
 viewcover:
 	xdg-open cover/index.html
 
diff --git a/utils/docs/man/man1/atomic-openshift-installer.1 b/utils/docs/man/man1/atomic-openshift-installer.1
new file mode 100644
index 000000000..4da82191b
--- /dev/null
+++ b/utils/docs/man/man1/atomic-openshift-installer.1
@@ -0,0 +1,186 @@
+'\" t
+.\"     Title: atomic-openshift-installer
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\"      Date: 09/28/2016
+.\"    Manual: atomic-openshift-installer
+.\"    Source: atomic-openshift-utils 1.3
+.\"  Language: English
+.\"
+.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/28/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer"
+.\" -----------------------------------------------------------------
+.\" * 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"
+atomic-openshift-installer \- Interactive OpenShift Container Platform (OCP) installer
+.SH "SYNOPSIS"
+.sp
+atomic\-openshift\-installer [OPTIONS] COMMAND [OPTS]
+.SH "DESCRIPTION"
+.sp
+\fBatomic\-openshift\-installer\fR makes the process for installing OCP easier by interactively gathering the data needed to run on each host\&. It can also be run in unattended mode if provided with a configuration file\&.
+.SH "OPTIONS"
+.sp
+The following options are common to all commands\&.
+.PP
+\fB\-u\fR, \fB\-\-unattended\fR
+.RS 4
+Run installer in
+\fBunattended\fR
+mode\&. You will not be prompted to answer any questions\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-configuration\fR \fIPATH\fR
+.RS 4
+Provide an alternate
+\fIPATH\fR
+to an
+\fIinstaller\&.cfg\&.yml\fR
+file\&.
+.RE
+.PP
+\fB\-a\fR \fIDIRECTORY\fR, \fB\-\-ansible\-playbook\-directory\fR \fIDIRECTORY\fR
+.RS 4
+Manually set the
+\fIDIRECTORY\fR
+in which to look for Ansible playbooks\&.
+.RE
+.PP
+\fB\-\-ansible\-log\-path\fR \fIPATH\fR
+.RS 4
+Specify the
+\fIPATH\fR
+of the directory in which to save Ansible logs\&.
+.RE
+.PP
+\fB\-v\fR, \fB\-\-verbose\fR
+.RS 4
+Run the installer with more verbosity\&.
+.RE
+.PP
+\fB\-d\fR, \fB\-\-debug\fR
+.RS 4
+Enable installer debugging\&. Logs are saved in
+\fI/tmp/installer\&.txt\fR\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Show the usage help and exit\&.
+.RE
+.SH "COMMANDS"
+.sp
+\fBatomic\-openshift\-installer\fR has three modes of operation:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBinstall\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBuninstall\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fBupgrade\fR
+.RE
+.sp
+The options specific to each command are described in the following sections\&.
+.SH "INSTALL"
+.sp
+The \fBinstall\fR command will guide you through steps required to install an OCP cluster\&. After all of the required information has been collected (target hosts, storage options, high\-availability), the installation will begin\&.
+.PP
+\fB\-f\fR, \fB\-\-force\fR
+.RS 4
+Forces an installation\&. This means that hosts with existing installations will be reinstalled if required\&.
+.RE
+.PP
+\fB\-\-gen\-inventory\fR
+.RS 4
+Generate an Ansible inventory file and exit\&. The default location for the inventory file is
+\fI~/\&.config/openshift/hosts\fR\&.
+.RE
+.SH "UNINSTALL"
+.sp
+The \fBuninstall\fR command will uninstall OCP from your target hosts\&. This command has no additional options\&.
+.SH "UPGRADE"
+.sp
+The \fBupgrade\fR command will upgrade a cluster of hosts to a newer version of OCP\&.
+.PP
+\fB\-l\fR, \fB\-\-latest\-minor\fR
+.RS 4
+Upgrade to the latest minor version\&. For example, if you are running version
+\fB3\&.2\&.1\fR
+then this could upgrade you to
+\fB3\&.2\&.2\fR\&.
+.RE
+.PP
+\fB\-n\fR, \fB\-\-next\-major\fR
+.RS 4
+Upgrade to the latest major version\&. For example, if you are running version
+\fB3\&.2\fR
+then this could upgrade you to
+\fB3\&.3\fR\&.
+.RE
+.SH "FILES"
+.sp
+\fB~/\&.config/openshift/installer\&.cfg\&.yml\fR \(em Installer configuration file\&. Can be used to generate an inventory later or start an unattended installation\&.
+.sp
+\fB~/\&.config/openshift/hosts\fR \(em Generated Ansible inventory file\&. Used to run the Ansible playbooks for install, uninstall, and upgrades\&.
+.sp
+\fB/tmp/ansible\&.log\fR \(em The default location of the ansible log file\&.
+.sp
+\fB/tmp/installer\&.txt\fR \(em The location of the log file for debugging the installer\&.
+.SH "AUTHOR"
+.sp
+Red Hat OpenShift Productization team
+.sp
+For a complete list of contributors, please visit the GitHub charts page\&.
+.SH "COPYRIGHT"
+.sp
+Copyright \(co 2016 Red Hat, Inc\&.
+.sp
+\fBatomic\-openshift\-installer\fR is released under the terms of the ASL 2\&.0 license\&.
+.SH "SEE ALSO"
+.sp
+\fBansible\fR(1), \fBansible\-playbook\fR(1)
+.sp
+\fBThe openshift\-ansible GitHub Project\fR \(em https://github\&.com/openshift/openshift\-ansible/
+.sp
+\fBThe atomic\-openshift\-installer Documentation\fR \(em https://docs\&.openshift\&.com/container\-platform/3\&.3/install_config/install/quick_install\&.html
diff --git a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
new file mode 100644
index 000000000..64e5d14a3
--- /dev/null
+++ b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in
@@ -0,0 +1,167 @@
+atomic-openshift-installer(1)
+=============================
+:man source:   atomic-openshift-utils
+:man version:  %VERSION%
+:man manual:   atomic-openshift-installer
+
+
+NAME
+----
+atomic-openshift-installer - Interactive OpenShift Container Platform (OCP) installer
+
+
+SYNOPSIS
+--------
+atomic-openshift-installer [OPTIONS] COMMAND [OPTS]
+
+
+DESCRIPTION
+-----------
+
+**atomic-openshift-installer** makes the process for installing OCP
+easier by interactively gathering the data needed to run on each
+host. It can also be run in unattended mode if provided with a
+configuration file.
+
+
+OPTIONS
+-------
+
+The following options are common to all commands.
+
+*-u*, *--unattended*::
+
+Run installer in **unattended** mode. You will not be prompted to
+answer any questions.
+
+
+*-c*, *--configuration* 'PATH'::
+
+Provide an alternate 'PATH' to an 'installer.cfg.yml' file.
+
+
+*-a* 'DIRECTORY', *--ansible-playbook-directory* 'DIRECTORY'::
+
+Manually set the 'DIRECTORY' in which to look for Ansible playbooks.
+
+
+*--ansible-log-path* 'PATH'::
+
+Specify the 'PATH' of the directory in which to save Ansible logs.
+
+
+*-v*, *--verbose*::
+
+Run the installer with more verbosity.
+
+
+*-d*, *--debug*::
+
+Enable installer debugging. Logs are saved in '/tmp/installer.txt'.
+
+
+*-h*, *--help*::
+
+Show the usage help and exit.
+
+
+COMMANDS
+--------
+
+**atomic-openshift-installer** has three modes of operation:
+
+* **install**
+* **uninstall**
+* **upgrade**
+
+The options specific to each command are described in the following
+sections.
+
+
+
+INSTALL
+-------
+
+The **install** command will guide you through steps required to
+install an OCP cluster. After all of the required information has been
+collected (target hosts, storage options, high-availability), the
+installation will begin.
+
+*-f*, *--force*::
+
+Forces an installation. This means that hosts with existing
+installations will be reinstalled if required.
+
+*--gen-inventory*::
+
+Generate an Ansible inventory file and exit. The default location for
+the inventory file is '~/.config/openshift/hosts'.
+
+
+UNINSTALL
+---------
+
+The **uninstall** command will uninstall OCP from your target
+hosts. This command has no additional options.
+
+
+UPGRADE
+-------
+
+The **upgrade** command will upgrade a cluster of hosts to a newer
+version of OCP.
+
+*-l*, *--latest-minor*::
+
+Upgrade to the latest minor version. For example, if you are running
+version **3.2.1** then this could upgrade you to **3.2.2**.
+
+*-n*, *--next-major*::
+
+Upgrade to the latest major version. For example, if you are running
+version **3.2** then this could upgrade you to **3.3**.
+
+
+
+FILES
+-----
+
+*~/.config/openshift/installer.cfg.yml* -- Installer configuration
+ file. Can be used to generate an inventory later or start an
+ unattended installation.
+
+*~/.config/openshift/hosts* -- Generated Ansible inventory file. Used
+ to run the Ansible playbooks for install, uninstall, and upgrades.
+
+*/tmp/ansible.log* -- The default location of the ansible log file.
+
+*/tmp/installer.txt* -- The location of the log file for debugging the
+ installer.
+
+
+AUTHOR
+------
+
+Red Hat OpenShift Productization team
+
+For a complete list of contributors, please visit the GitHub charts
+page.
+
+
+
+COPYRIGHT
+---------
+Copyright © 2016 Red Hat, Inc.
+
+**atomic-openshift-installer** is released under the terms of the ASL
+2.0 license.
+
+
+
+SEE ALSO
+--------
+*ansible*(1), *ansible-playbook*(1)
+
+*The openshift-ansible GitHub Project* -- <https://github.com/openshift/openshift-ansible/>
+
+*The atomic-openshift-installer Documentation* -- <https://docs.openshift.com/container-platform/3.3/install_config/install/quick_install.html>