Updated doc strings post refactor. Updated documentation for better readability and table of contents

Author: Dan

doc/conf.py

@@ -57,16 +57,16 @@
 
 # General information about the project.
 project = u'Parallel-SSH'
-copyright = u'2015, P Kittenis'
+copyright = u'2015-, P Kittenis'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.70'
+version = '0.80'
 # The full version, including alpha/beta/rc tags.
-release = '0.70.2'
+release = '0.80.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/exceptions.rst

@@ -0,0 +1,5 @@
+Exceptions
+==========
+
+.. automodule:: pssh.exceptions
+    :member-order: groupwise

doc/index.rst

@@ -7,22 +7,22 @@ Parallel-SSH's documentation
 ============================
 
 .. toctree::
-   :maxdepth: 4
    :hidden:
-   :titlesonly:
 
    self
 
-Welcome to ParallelSSH's API documentation.
+.. toctree::
 
-New users should start with :mod:`pssh.ParallelSSHClient.run_command`.
+   pssh_client
+   ssh_client
+   exceptions
+
+Welcome to ParallelSSH's API documentation.
 
-.. automodule:: pssh
-    :member-order: groupwise
+New users should start with :mod:`pssh.pssh_client.ParallelSSHClient.run_command`.
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`search`

doc/pssh_client.rst

@@ -0,0 +1,5 @@
+ParallelSSHClient API Documentation
+===================================
+
+.. automodule:: pssh.pssh_client
+    :member-order: groupwise

doc/ssh_client.rst

@@ -0,0 +1,5 @@
+SSHClient API Documentation
+===========================
+
+.. automodule:: pssh.ssh_client
+    :member-order: groupwise

pssh/pssh_client.py

@@ -35,7 +35,7 @@
 
 
 class ParallelSSHClient(object):
-    """Uses :mod:`pssh.SSHClient`, performs tasks over SSH on multiple hosts in \
+    """Uses :mod:`pssh.ssh_client.SSHClient`, performs tasks over SSH on multiple hosts in \
     parallel.
 
     Connections to hosts are established in parallel when ``run_command`` is called,
@@ -169,13 +169,15 @@ def run_command(self, *args, **kwargs):
         :type sudo: bool
         :param kwargs: Keyword arguments for command
         :type kwargs: dict
-
-        :rtype: Dictionary with host as key as per :mod:`ParallelSSH.get_output`
+        :param stop_on_errors: (Optional) Raise exception on errors running command. \
+        Defaults to True.
+        :type stop_on_errors: bool
+        :rtype: Dictionary with host as key as per :mod:`pssh.pssh_client.ParallelSSH.get_output`
         
-        :raises: :mod:`pssh.AuthenticationException` on authentication error
-        :raises: :mod:`pssh.UnknownHostException` on DNS resolution error
-        :raises: :mod:`pssh.ConnectionErrorException` on error connecting
-        :raises: :mod:`pssh.SSHException` on other undefined SSH errors
+        :raises: :mod:`pssh.exceptions.AuthenticationException` on authentication error
+        :raises: :mod:`pssh.exceptions.UnknownHostException` on DNS resolution error
+        :raises: :mod:`pssh.exceptions.ConnectionErrorException` on error connecting
+        :raises: :mod:`pssh.exceptions.SSHException` on other undefined SSH errors
 
         **Example Usage**
         
@@ -234,7 +236,7 @@ def run_command(self, *args, **kwargs):
     def exec_command(self, *args, **kwargs):
         """Run command on all hosts in parallel, honoring `self.pool_size`
         
-        **Deprecated by** :mod:`pssh.ParallelSSHClient.run_command`
+        **Deprecated by** :mod:`pssh.pssh_client.ParallelSSHClient.run_command`
         
         :param args: Position arguments for command
         :type args: tuple
@@ -265,11 +267,11 @@ def get_output(self, cmd, output):
         
         :param cmd: Command to get output from
         :type cmd: :mod:`gevent.Greenlet`
-        :param output: Dictionary containing output to be updated with output
+        :param output: Dictionary containing output to be updated with output \
         from cmd
         :type output: dict
         :rtype: None
-
+        
         `output` parameter is modified in-place and has the following structure
         
         ::

pssh/ssh_client.py

@@ -122,8 +122,10 @@ def _connect_tunnel(self):
         """Connects to SSH server via an intermediate SSH tunnel server.
         client (me) -> tunnel (ssh server to proxy through) -> \
         destination (ssh server to run command)
+        
         :rtype: `:mod:paramiko.SSHClient` Client to remote SSH destination
-        via intermediate SSH tunnel server."""
+        via intermediate SSH tunnel server.
+        """
         self.proxy_client = paramiko.SSHClient()
         self.proxy_client.set_missing_host_key_policy(paramiko.MissingHostKeyPolicy())
         self._connect(self.proxy_client, self.proxy_host, self.proxy_port)
@@ -137,10 +139,10 @@ def _connect_tunnel(self):
     def _connect(self, client, host, port, sock=None, retries=1):
         """Connect to host
         
-        :raises: :mod:`pssh.AuthenticationException` on authentication error
-        :raises: :mod:`pssh.UnknownHostException` on DNS resolution error
-        :raises: :mod:`pssh.ConnectionErrorException` on error connecting
-        :raises: :mod:`pssh.SSHException` on other undefined SSH errors
+        :raises: :mod:`pssh.exceptions.AuthenticationException` on authentication error
+        :raises: :mod:`pssh.exceptions.UnknownHostException` on DNS resolution error
+        :raises: :mod:`pssh.exceptions.ConnectionErrorException` on error connecting
+        :raises: :mod:`pssh.exceptions.SSHException` on other undefined SSH errors
         """
         try:
             client.connect(host, username=self.user,