Rearrange existing documentation to fit the new standard layout

Change-Id: If0c0789ac730c565477b9053d63375c67667b0d1

3 files changed, 187 insertions, 0 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..251e71c
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,8 @@
+======================================
+python-ironicclient User Documentation
+======================================
+
+.. toctree::
+
+   ironic_client
+   osc_plugin_cli
diff --git a/doc/source/cli/ironic_client.rst b/doc/source/cli/ironic_client.rst
new file mode 100644
index 0000000..92c02b0
--- /dev/null
+++ b/doc/source/cli/ironic_client.rst
@@ -0,0 +1,94 @@
+==========================================
+Ironic Client Command-Line Interface (CLI)
+==========================================
+
+.. program:: ironic
+.. highlight:: bash
+
+SYNOPSIS
+========
+
+:program:`ironic` [options] <command> [command-options]
+
+:program:`ironic help`
+
+:program:`ironic help` <command>
+
+
+DESCRIPTION
+===========
+
+The :program:`ironic` command-line interface (CLI) interacts with the
+OpenStack Bare Metal Service (Ironic).
+
+In order to use the CLI, you must provide your OpenStack username, password,
+project (historically called tenant), and auth endpoint. You can use
+configuration options :option:`--os-username`, :option:`--os-password`,
+:option:`--os-tenant-id` (or :option:`--os-tenant-name`),
+and :option:`--os-auth-url`, or set the corresponding
+environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_PROJECT_ID=b363706f891f48019483f8bd6503c54b  # or OS_PROJECT_NAME
+    $ export OS_PROJECT_NAME=project                         # or OS_PROJECT_ID
+    $ export OS_AUTH_URL=http://auth.example.com:5000/v2.0
+
+The command-line tool will attempt to reauthenticate using the provided
+credentials for every request. You can override this behavior by manually
+supplying an auth token using :option:`--ironic-url` and
+:option:`--os-auth-token`, or by setting the corresponding environment
+variables::
+
+    $ export IRONIC_URL=http://ironic.example.org:6385/
+    $ export OS_AUTH_TOKEN=3bcc3d3a03f44e3d8377f9247b0ad155
+
+Since Keystone can return multiple regions in the Service Catalog, you can
+specify the one you want with :option:`--os-region-name` or set the following
+environment variable. (It defaults to the first in the list returned.)
+::
+
+    export OS_REGION_NAME=region
+
+Ironic CLI supports bash completion. The command-line tool can automatically
+fill partially typed commands. To use this feature, source the below file
+(available at
+https://git.openstack.org/cgit/openstack/python-ironicclient/tree/tools/ironic.bash_completion)
+to your terminal and then bash completion should work::
+
+    $ source ironic.bash_completion
+
+To avoid doing this every time, add this to your ``.bashrc`` or copy the
+ironic.bash_completion file to the default bash completion scripts directory
+on your linux distribution.
+
+OPTIONS
+=======
+
+To get a list of available (sub)commands and options, run::
+
+    $ ironic help
+
+To get usage and options of a command, run::
+
+    $ ironic help <command>
+
+
+EXAMPLES
+========
+
+Get information about the node-create command::
+
+    $ ironic help node-create
+
+Get a list of available drivers::
+
+    $ ironic driver-list
+
+Enroll a node with "fake" deploy driver and "ipmitool" power driver::
+
+    $ ironic node-create -d fake_ipmitool -i ipmi_address=1.2.3.4
+
+Get a list of nodes::
+
+    $ ironic node-list
diff --git a/doc/source/cli/osc_plugin_cli.rst b/doc/source/cli/osc_plugin_cli.rst
new file mode 100644
index 0000000..924d3e5
--- /dev/null
+++ b/doc/source/cli/osc_plugin_cli.rst
@@ -0,0 +1,85 @@
+=============================================
+OpenStack Client Command-Line Interface (CLI)
+=============================================
+
+.. program:: openstack baremetal
+.. highlight:: bash
+
+Synopsis
+========
+
+:program:`openstack [options] baremetal` <command> [command-options]
+
+:program:`openstack help baremetal` <command>
+
+
+Description
+===========
+
+The OpenStack Client plugin interacts with the Bare Metal service
+through the ``openstack baremetal`` command line interface (CLI).
+
+To use ``openstack`` CLI, the OpenStackClient should be installed::
+
+    # pip install python-openstackclient
+
+To use the CLI, you must provide your OpenStack username, password,
+project, and auth endpoint. You can use configuration options
+:option:`--os-username`, :option:`--os-password`, :option:`--os-project-id`
+(or :option:`--os-project-name`), and :option:`--os-auth-url`,
+or set the corresponding environment variables::
+
+    $ export OS_USERNAME=user
+    $ export OS_PASSWORD=password
+    $ export OS_PROJECT_NAME=project                         # or OS_PROJECT_ID
+    $ export OS_PROJECT_DOMAIN_ID=default
+    $ export OS_USER_DOMAIN_ID=default
+    $ export OS_IDENTITY_API_VERSION=3
+    $ export OS_AUTH_URL=http://auth.example.com:5000/identity
+
+This CLI is provided by python-openstackclient and osc-lib projects:
+
+* https://git.openstack.org/openstack/python-openstackclient
+* https://git.openstack.org/openstack/osc-lib
+
+
+Getting help
+============
+
+To get a list of available (sub)commands and options, run::
+
+    $ openstack help baremetal
+
+To get usage and options of a command, run::
+
+    $ openstack help baremetal <sub-command>
+
+
+Examples
+========
+
+Get information about the openstack baremetal node create command::
+
+    $ openstack help baremetal node create
+
+Get a list of available drivers::
+
+    $ openstack baremetal driver list
+
+Enroll a node with "agent_ipmitool" driver::
+
+    $ openstack baremetal node create --driver agent_ipmitool --driver-info ipmi_address=1.2.3.4
+
+Get a list of nodes::
+
+    $ openstack baremetal node list
+
+The baremetal API version can be specified via:
+
+* environment variable OS_BAREMETAL_API_VERSION::
+
+    $ export OS_BAREMETAL_API_VERSION=1.25
+
+* or optional command line argument --os-baremetal-api-version::
+
+    $ openstack baremetal port group list --os-baremetal-api-version 1.25