Improve docstrings and README

Change-Id: If24d9c66be9a5e9eab6f1a364c531c01d5e53665
Story: 2006608
Task: 36776

README.rst

@@ -1,34 +1,22 @@
-========
-sushycli
-========
 
+About Sushy CLI
+===============
 
-.. image:: https://img.shields.io/pypi/v/sushycli.svg
-        :target: https://pypi.python.org/pypi/sushycli
+Sushy CLI tool is intended to help human beings to communicate with `Redfish`_
+based baseboard management controllers (BMC).
 
-.. image:: https://img.shields.io/travis/khansaAmrouni/sushycli.svg
-        :target: https://travis-ci.org/khansaAmrouni/sushycli
+BMCs offer powerful means of controlling bare metal machines. For example, one
+can flip machine power, change BIOS configuration or even flash the firmware.
 
-.. image:: https://readthedocs.org/projects/sushycli/badge/?version=latest
-        :target: https://sushycli.readthedocs.io/en/latest/?badge=latest
-        :alt: Documentation Status
+The `sushycli` tool offers a friendly command-line interface to some of the BMC
+features. It's main audience include software developers working on bare metal
+management automation and system administrators handling the raw iron with bare
+hands.
 
+* Free software: Apache license
+* Documentation: https://docs.openstack.org/sushy-cli/latest/
+* Usage: https://docs.openstack.org/sushy-cli/latest/reference/usage.html
+* Source: https://opendev.org/openstack/sushy-cli
+* Bugs: https://storyboard.openstack.org/#!/project/960
 
-
-
-a Redfish command line interface client tool built on top of sushy library to manage Redfish BMC resources.
-
-
-* Free software: Apache Software License 2.0
-* Documentation: https://docs.openstack.org/sushycli/latest/
-
-
-Usage
---------
-
-In order to get you a copy of the project up and running on your local machine follow these steps:
-
-* Clone the project 
-* Run python setup.py install  
-* Run pip install -e . 
-
+.. _Redfish: http://www.dmtf.org/standards/redfish

sushycli/base.py

@@ -21,6 +21,10 @@ from cliff import lister
 
 
 class BaseParserMixIn(object):
+    """Common bits and pieces of all `sushycli` commands.
+
+    Does not implement any CLI command by its own.
+    """
 
     def _add_options(self, parser):
 
@@ -41,8 +45,12 @@ class BaseParserMixIn(object):
         return parser
 
     def take_action(self, args):
-        """Common command action"""
+        """Common base for all command actions
 
+        :param args: a namespace of command-line option-value pairs that
+            come from the user
+        :returns: CLI process exit code
+        """
         root = sushy.Sushy(
             args.service_endpoint, username=args.username,
             password=args.password)
@@ -51,20 +59,28 @@ class BaseParserMixIn(object):
 
 
 class BaseCommand(BaseParserMixIn, command.Command):
-    """Common base for all sushycli commands"""
+    """Common base for all sushycli status commands"""
 
     def get_parser(self, prog_name):
-        """Common command parser"""
+        """Common base for all status command parsers.
+
+        :param prog_name: name of the cliff command being executed
+        :returns: an `argparse.ArgumentParser` instance
+        """
         parser = super(BaseCommand, self).get_parser(prog_name)
 
         return self._add_options(parser)
 
 
 class BaseLister(BaseParserMixIn, lister.Lister):
-    """Common base for all sushycli listers"""
+    """Common base for all sushycli listing commands"""
 
     def get_parser(self, prog_name):
-        """Common lister parser"""
+        """Common base for all listing command parsers.
+
+        :param prog_name: name of the cliff command being executed
+        :returns: an `argparse.ArgumentParser` instance
+        """
         parser = super(BaseLister, self).get_parser(prog_name)
 
         return self._add_options(parser)

sushycli/cmd/sushycli.py

@@ -21,6 +21,14 @@ from cliff.commandmanager import CommandManager
 
 
 class SushyCliApp(App):
+    """Cliff application for the `sushycli` tool.
+
+    :param description: one-liner explaining the program purpose
+    :param version: application version number
+    :param command_manager: plugin loader
+    :param deferred_help: Allow subcommands to accept `–help` with allowing
+        to defer help print after initialize_app
+    """
 
     def __init__(self):
         super(SushyCliApp, self).__init__(

sushycli/system_power.py

@@ -31,7 +31,11 @@ class SystemPowerShow(base.BaseLister):
     """Show machine power state"""
 
     def get_parser(self, prog_name):
-        """SystemPowerShow state command parser"""
+        """Power state management command parser.
+
+        :param prog_name: name of the cliff command being executed
+        :returns: an `argparse.ArgumentParser` instance
+        """
         parser = super(SystemPowerShow, self).get_parser(prog_name)
 
         parser.add_argument(
@@ -42,8 +46,12 @@ class SystemPowerShow(base.BaseLister):
         return parser
 
     def take_action(self, args):
-        """SystemPowerShow state command action"""
+        """Power state management command action.
 
+        :param args: a namespace of command-line option-value pairs that
+            come from the user
+        :returns: CLI process exit code
+        """
         root = super(SystemPowerShow, self).take_action(args)
 
         sys_inst = root.get_system(args.system_id)
@@ -55,7 +63,11 @@ class SystemPowerSet(base.BaseCommand):
     """Change machine power state"""
 
     def get_parser(self, prog_name):
-        """SystemPowerSet state command parser"""
+        """Power state management command parser.
+
+        :param prog_name: name of the cliff command being executed
+        :returns: an `argparse.ArgumentParser` instance
+        """
         parser = super(SystemPowerSet, self).get_parser(prog_name)
 
         parser.add_argument(
@@ -73,8 +85,12 @@ class SystemPowerSet(base.BaseCommand):
         return parser
 
     def take_action(self, args):
-        """SystemPowerSet state command action"""
+        """Power state management command action.
 
+        :param args: a namespace of command-line option-value pairs that
+            come from the user
+        :returns: CLI process exit code
+        """
         root = super(SystemPowerSet, self).take_action(args)
 
         sys_inst = root.get_system(args.system_id)

sushycli/version.py

@@ -18,17 +18,27 @@ from sushycli.base import BaseLister
 
 
 class VersionShow(BaseLister):
-    """Read supported Redfish protocol version of remote agent"""
+    """Read supported Redfish protocol version of remote agent.
 
+    Implements `sushycli version` command.
+    """
     def get_parser(self, prog_name):
-        """Redfish version command parser"""
+        """Redfish versioin command parser.
+
+        :param prog_name: name of the cliff command being executed
+        :returns: an `argparse.ArgumentParser` instance
+        """
         parser = super(VersionShow, self).get_parser(prog_name)
 
         return parser
 
     def take_action(self, args):
-        """Redfish version command action"""
+        """Redfish version command action
 
+        :param args: a namespace of command-line option-value pairs that
+            come from the user
+        :returns: CLI process exit code
+        """
         root = super(VersionShow, self).take_action(args)
 
         return ['Version'], [[root.redfish_version]]