From ee76824bd773ca91a0e76af61d96547ff4b196ba Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Tue, 27 Sep 2016 08:14:18 -0700 Subject: Add a manpage for atomic-openshift-installer --- utils/Makefile | 21 +++ utils/docs/man/man1/atomic-openshift-installer.1 | 186 +++++++++++++++++++++ .../man1/atomic-openshift-installer.1.asciidoc.in | 167 ++++++++++++++++++ 3 files changed, 374 insertions(+) create mode 100644 utils/docs/man/man1/atomic-openshift-installer.1 create mode 100644 utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in (limited to 'utils') 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..8800b5d13 --- /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 +.\" Date: 09/27/2016 +.\" Manual: atomic-openshift-installer +.\" Source: atomic-openshift-utils 1.3 +.\" Language: English +.\" +.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/27/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 installer +.SH "SYNOPSIS" +.sp +atomic\-openshift\-installer [OPTIONS] COMMAND [OPTS] +.SH "DESCRIPTION" +.sp +\fBatomic\-openshift\-installer\fR makes the process for installing OSE or AEP 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 +to look for Ansible playbooks in\&. +.RE +.PP +\fB\-\-ansible\-log\-path\fR \fIPATH\fR +.RS 4 +Specify the +\fIPATH\fR +of the directory to save Ansible logs in\&. +.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 throgh steps required to install an OpenShift Container Platform\&. 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 OpenShift Container Platform 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 the OpenShift Container Platform\&. +.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..d695b98b6 --- /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 installer + + +SYNOPSIS +-------- +atomic-openshift-installer [OPTIONS] COMMAND [OPTS] + + +DESCRIPTION +----------- + +**atomic-openshift-installer** makes the process for installing OSE or +AEP 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' to look for Ansible playbooks in. + + +*--ansible-log-path* 'PATH':: + +Specify the 'PATH' of the directory to save Ansible logs in. + + +*-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 throgh steps required to +install an OpenShift Container Platform. 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 OpenShift Container Platform +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 the OpenShift Container Platform. + +*-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* -- + +*The atomic-openshift-installer Documentation* -- -- cgit v1.2.3 From d831377f61a1c605725cafeee774891899dbe90b Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Tue, 27 Sep 2016 13:50:26 -0700 Subject: Addresses most comments from @adellape --- .../man1/atomic-openshift-installer.1.asciidoc.in | 24 +++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'utils') diff --git a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in index d695b98b6..64e5d14a3 100644 --- a/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in +++ b/utils/docs/man/man1/atomic-openshift-installer.1.asciidoc.in @@ -7,7 +7,7 @@ atomic-openshift-installer(1) NAME ---- -atomic-openshift-installer - Interactive OpenShift Container Platform installer +atomic-openshift-installer - Interactive OpenShift Container Platform (OCP) installer SYNOPSIS @@ -18,8 +18,8 @@ atomic-openshift-installer [OPTIONS] COMMAND [OPTS] DESCRIPTION ----------- -**atomic-openshift-installer** makes the process for installing OSE or -AEP easier by interactively gathering the data needed to run on each +**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. @@ -42,12 +42,12 @@ Provide an alternate 'PATH' to an 'installer.cfg.yml' file. *-a* 'DIRECTORY', *--ansible-playbook-directory* 'DIRECTORY':: -Manually set the 'DIRECTORY' to look for Ansible playbooks in. +Manually set the 'DIRECTORY' in which to look for Ansible playbooks. *--ansible-log-path* 'PATH':: -Specify the 'PATH' of the directory to save Ansible logs in. +Specify the 'PATH' of the directory in which to save Ansible logs. *-v*, *--verbose*:: @@ -82,10 +82,10 @@ sections. INSTALL ------- -The **install** command will guide you throgh steps required to -install an OpenShift Container Platform. After all of the required -information has been collected (target hosts, storage options, -high-availability) the installation will begin. +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*:: @@ -101,15 +101,15 @@ the inventory file is '~/.config/openshift/hosts'. UNINSTALL --------- -The **uninstall** command will uninstall OpenShift Container Platform -from your target hosts. This command has no additional options. +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 the OpenShift Container Platform. +version of OCP. *-l*, *--latest-minor*:: -- cgit v1.2.3 From 20a07aed5d105fdb06377b62f2e88f067963135f Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Wed, 28 Sep 2016 08:07:49 -0700 Subject: Update spec file to install manpage --- utils/docs/man/man1/atomic-openshift-installer.1 | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'utils') diff --git a/utils/docs/man/man1/atomic-openshift-installer.1 b/utils/docs/man/man1/atomic-openshift-installer.1 index 8800b5d13..4da82191b 100644 --- a/utils/docs/man/man1/atomic-openshift-installer.1 +++ b/utils/docs/man/man1/atomic-openshift-installer.1 @@ -2,12 +2,12 @@ .\" Title: atomic-openshift-installer .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 09/27/2016 +.\" Date: 09/28/2016 .\" Manual: atomic-openshift-installer .\" Source: atomic-openshift-utils 1.3 .\" Language: English .\" -.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/27/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer" +.TH "ATOMIC\-OPENSHIFT\-I" "1" "09/28/2016" "atomic\-openshift\-utils 1\&.3" "atomic\-openshift\-installer" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -28,13 +28,13 @@ .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" -atomic-openshift-installer \- Interactive OpenShift Container Platform installer +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 OSE or AEP 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\&. +\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\&. @@ -59,14 +59,14 @@ file\&. .RS 4 Manually set the \fIDIRECTORY\fR -to look for Ansible playbooks in\&. +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 to save Ansible logs in\&. +of the directory in which to save Ansible logs\&. .RE .PP \fB\-v\fR, \fB\-\-verbose\fR @@ -124,7 +124,7 @@ Show the usage help and exit\&. The options specific to each command are described in the following sections\&. .SH "INSTALL" .sp -The \fBinstall\fR command will guide you throgh steps required to install an OpenShift Container Platform\&. After all of the required information has been collected (target hosts, storage options, high\-availability) the installation will begin\&. +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 @@ -138,10 +138,10 @@ Generate an Ansible inventory file and exit\&. The default location for the inve .RE .SH "UNINSTALL" .sp -The \fBuninstall\fR command will uninstall OpenShift Container Platform from your target hosts\&. This command has no additional options\&. +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 the OpenShift Container Platform\&. +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 -- cgit v1.2.3