more doc updates

Author: shikhar

docs/source/conf.py

@@ -196,3 +196,5 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+autoclass_content = 'both'

docs/source/operations.rst

@@ -1,7 +1,6 @@
 :mod:`~ncclient.operations` -- Everything RPC
 =============================================
 
-
 .. module:: ncclient.operations
     :synopsis: Everything RPC
 
@@ -11,7 +10,7 @@
 Base classes
 ------------
 
-.. autoclass:: RPC(session, async=False, timeout=None, raise_mode="none")
+.. autoclass:: RPC
     :members: DEPENDS, REPLY_CLS, _assert, _request, request, event, error, reply, raise_mode, is_async, timeout
 
 .. autoclass:: RPCReply
@@ -24,15 +23,74 @@ Base classes
 Operations
 ----------
 
-The operation classes are currently undocumented. See documentation of :class:`~ncclient.manager.Manager` for methods that utilize the operation classes. The parameters accepted by :meth:`~RPC.request` for these classes are the same.
+Retrieval
+..........
+
+.. autoclass:: Get
+    :members: request
+    :show-inheritance:
+
+    .. autoattribute:: REPLY_CLS
 
-Replies with data
------------------
+.. autoclass:: GetConfig
+    :members: request
+    :show-inheritance:
+
+    .. autoattribute:: REPLY_CLS
 
 .. autoclass:: GetReply
     :show-inheritance:
     :members: data, data_ele, data_xml
 
+Editing
+........
+
+.. autoclass:: EditConfig
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: DeleteConfig
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: CopyConfig
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: Validate
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: Commit
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: DiscardChanges
+    :members: request
+    :show-inheritance:
+
+Locking
+........
+
+.. autoclass:: Lock
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: Unlock
+    :members: request
+    :show-inheritance:
+
+Session
+........
+
+.. autoclass:: CloseSession
+    :members: request
+    :show-inheritance:
+
+.. autoclass:: KillSession
+    :members: request
+    :show-inheritance:
+
 Exceptions
 ----------
 

ncclient/operations/edit.py

@@ -123,7 +123,7 @@ def request(self, confirmed=False, timeout=None):
 
         *confirmed* whether this is a confirmed commit
 
-        *timeout* confirm timeout in seconds"""
+        *timeout* specifies the confirm timeout in seconds"""
         node = new_ele("commit")
         if confirmed:
             self._assert(":confirmed-commit")

ncclient/operations/retrieve.py

@@ -20,8 +20,7 @@
 
 class GetReply(RPCReply):
 
-    """Adds attributes for the *data* element to `RPCReply`. This pertains to the `Get` and
-    `GetConfig` operations."""
+    """Adds attributes for the *data* element to `RPCReply`."""
 
     def _parsing_hook(self, root):
         self._data = None
@@ -51,6 +50,7 @@ class Get(RPC):
     "The *get* RPC."
 
     REPLY_CLS = GetReply
+    "See :class:`GetReply`."
 
     def request(self, filter=None):
         """Retrieve running configuration and device state information.
@@ -70,6 +70,7 @@ class GetConfig(RPC):
     "The *get-config* RPC."
 
     REPLY_CLS = GetReply
+    "See :class:`GetReply`."
 
     def request(self, source, filter=None):
         """Retrieve all or part of a specified configuration.

ncclient/operations/rpc.py

@@ -95,7 +95,7 @@ class RPCReply:
 
     .. note::
         If the reply has not yet been parsed there is an implicit, one-time parsing overhead to
-        accessing the attributes defined by this class and any subclasses.
+        accessing some of the attributes defined by this class.
     """
 
     ERROR_CLS = RPCError
@@ -127,7 +127,7 @@ def parse(self):
         self._parsed = True
 
     def _parsing_hook(self, root):
-        "No-op by default. Gets given the *root* element."
+        "No-op by default. Gets passed the *root* element for the reply."
         pass
 
     @property
@@ -220,17 +220,24 @@ class RaiseMode(object):
 
 class RPC(object):
 
-    """Base class for all operations, directly corresponding to *rpc* requests. Handles making the
-    request, and taking delivery of the reply."""
+    """Base class for all operations, directly corresponding to *rpc* requests. Handles making the request, and taking delivery of the reply."""
 
     DEPENDS = []
-    """Subclasses can specify their dependencies on capabilities. List of URI's or abbreviated names, e.g. ':writable-running'. These are verified at the time of instantiation. If the capability is not available, a :exc:`MissingCapabilityError` is raised.
-    """
+    """Subclasses can specify their dependencies on capabilities as a list of URI's or abbreviated names, e.g. ':writable-running'. These are verified at the time of instantiation. If the capability is not available, :exc:`MissingCapabilityError` is raised."""
 
     REPLY_CLS = RPCReply
-    "Subclasses can specify a different reply class, but it should be a subclass of `RPCReply`."
+    "By default :class:`RPCReply`. Subclasses can specify a :class:`RPCReply` subclass."
 
     def __init__(self, session, async=False, timeout=30, raise_mode=RaiseMode.NONE):
+        """
+        *session* is the :class:`~ncclient.transport.Session` instance
+
+        *async* specifies whether the request is to be made asynchronously, see :attr:`is_async`
+
+        *timeout* is the timeout for a synchronous request, see :attr:`timeout`
+
+        *raise_mode* specifies the exception raising mode, see :attr:`raise_mode`
+        """
         self._session = session
         try:
             for cap in self.DEPENDS:
@@ -258,11 +265,9 @@ def _request(self, op):
         
         In synchronous mode, blocks until the reply is received and returns :class:`RPCReply`. Depending on the :attr:`raise_mode` a `rpc-error` element in the reply may lead to an :exc:`RPCError` exception.
         
-        In asynchronous mode, returns immediately, returning *self*. The :attr:`event` attribute will be set when the reply has been received (see :attr:`reply`) or an error occured (see :attr:`error`).
-        
-        *op* operation to be requested as an `~xml.etree.ElementTree.Element`
+        In asynchronous mode, returns immediately, returning `self`. The :attr:`event` attribute will be set when the reply has been received (see :attr:`reply`) or an error occured (see :attr:`error`).
         
-        Returns :class:`RPCReply` (sync) or :class:`RPC` (async)
+        *op* is the operation to be requested as an :class:`~xml.etree.ElementTree.Element`
         """
         logger.info('Requesting %r' % self.__class__.__name__)
         req = self._wrap(op)
@@ -290,7 +295,7 @@ def _request(self, op):
 
     def request(self):
         """Subclasses must implement this method. Typically only the request needs to be built as an
-        `~xml.etree.ElementTree.Element` and everything else can be handed off to
+        :class:`~xml.etree.ElementTree.Element` and everything else can be handed off to
         :meth:`_request`."""
         pass
 
@@ -338,7 +343,7 @@ def session(self):
 
     @property
     def event(self):
-        """`~threading.Event` that is set when reply has been received or when an error preventing
+        """:class:`~threading.Event` that is set when reply has been received or when an error preventing
         delivery of the reply occurs.
         """
         return self._event
@@ -359,7 +364,7 @@ def __set_timeout(self, timeout):
     """Depending on this exception raising mode, an `rpc-error` in the reply may be raised as an :exc:`RPCError` exception. Valid values are the constants defined in :class:`RaiseMode`. """
 
     is_async = property(fget=lambda self: self._async, fset=__set_async)
-    """Specifies whether this RPC will be / was requested asynchronously. By default RPC's are synchronous. """
+    """Specifies whether this RPC will be / was requested asynchronously. By default RPC's are synchronous."""
 
     timeout = property(fget=lambda self: self._timeout, fset=__set_timeout)
     """Timeout in seconds for synchronous waiting defining how long the RPC request will block on a reply before raising :exc:`TimeoutExpiredError`.

ncclient/transport/ssh.py

@@ -309,5 +309,5 @@ def run(self):
 
     @property
     def transport(self):
-        "Underlying `paramiko.Transport <http://www.lag.net/paramiko/docs/paramiko.Transport-class.html>`_ object. This makes it possible to call methods like set_keepalive on it."
+        "Underlying `paramiko.Transport <http://www.lag.net/paramiko/docs/paramiko.Transport-class.html>`_ object. This makes it possible to call methods like :meth:`~paramiko.Transport.set_keepalive` on it."
         return self._transport