commit 09e504731dd9285a43059bb3c28982cf45a4bec1
Author: Shikhar Bhushan <shikhar@schmizz.net>
Date:   Wed Sep 23 16:10:27 2009 +0000

    sphinx documentation for manager coming along nicely
    
    git-svn-id: http://ncclient.googlecode.com/svn/trunk@187 6dbcf712-26ac-11de-a2f3-1373824ab735

diff --git a/docs/source/manager.rst b/docs/source/manager.rst
index 2aaa935..289a92e 100644
--- a/docs/source/manager.rst
+++ b/docs/source/manager.rst
@@ -1,4 +1,291 @@
-High-level API
-==============
+:mod:`~ncclient.manager` -- High-level API
+==========================================
 
-Most use-cases are met by using the high-level :class:`Manager` API.
\ No newline at end of file
+.. module:: ncclient.manager
+    :synopsis: High-level API
+
+Factory functions
+-----------------
+
+A `Manager` instance is created using a factory function.
+
+.. function:: connect_ssh(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password, key_filename=None, allow_agent=True, look_for_keys=True])
+    
+    Initializes a NETCONF session over SSH, and creates a connected `Manager`
+    instance. *host* must be specified, all the other arguments are optional and
+    depend on the kind of host key verification and user authentication you want
+    to complete.
+    
+    For the purpose of host key verification, on POSIX systems a user's
+    :file:`~/.ssh/known_hosts` file is automatically considered. The
+    *unknown_host_cb* argument specifies a callback that will be invoked when
+    the server's host key cannot be verified. See
+    :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
+    
+    First, ``publickey`` authentication is attempted. If a specific
+    *key_filename* is specified, it will be loaded and authentication attempted
+    using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys
+    provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in
+    the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an
+    encrypted key file is encountered, the *password* argument will be used as a
+    decryption passphrase.
+    
+    If ``publickey`` authentication fails and the *password* argument has been
+    supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be
+    attempted.
+    
+    :param host: hostname or address on which to connect
+    :type host: `string`
+    
+    :param port: port on which to connect
+    :type port: `int`
+    
+    :param timeout: timeout for socket connect
+    :type timeout: `int`
+    
+    :param unknown_host_cb: optional; callback that is invoked when host key
+                            verification fails
+    :type unknown_host_cb: `function`
+    
+    :param username: username to authenticate with, if not specified the
+                        username of the logged-in user is used
+    :type username: `string`
+    
+    :param password: password for ``password`` authentication or passphrase for
+                        decrypting private key files
+    :type password: `string`
+    
+    :param key_filename: location of a private key file on the file system
+    :type key_filename: `string`
+    
+    :param allow_agent: whether to try connecting to SSH agent for keys
+    :type allow_agent: `bool`
+    
+    :param look_for_keys: whether to look in usual locations for keys
+    :type look_for_keys: `bool`
+    
+    :raises: :exc:`~ncclient.transport.SSHUnknownHostError`
+    :raises: :exc:`~ncclient.transport.AuthenticationError`
+    
+    :rtype: `Manager`
+    
+.. function:: connect()
+
+    Same as :func:`connect_ssh`, since SSH is the default (and currently, the
+    only) transport.
+
+Manager
+-------
+
+Exposes an API for RPC operations as method calls. The return type of these
+methods depends on whether we are is in :attr:`asynchronous or synchronous
+mode <ncclient.manager.Manager.async_mode>`.
+
+In synchronous mode replies are awaited and the corresponding
+`~ncclient.operations.RPCReply` object is returned. Depending on the
+:attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, an
+*rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
+
+However in asynchronous mode, operations return immediately with an
+`~ncclient.operations.RPC` object. Error handling and checking for whether a
+reply has been received must be dealt with manually. See the
+`~ncclient.operations.RPC` documentation for details.
+
+Note that in case of the *get* and *get-config* operations, the reply is an
+instance of `~ncclient.operations.GetReply` which exposes the additional
+attributes :attr:`~ncclient.operations.GetReply.data`
+(as `~xml.etree.ElementTree.Element`) and
+:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary
+interest in case of these operations.
+
+Presence of capabilities is verified to the extent possible, and you can expect
+a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In
+case of transport-layer errors, e.g. unexpected session close,
+:exc:`~ncclient.transport.TransportError` will be raised.
+
+.. class:: Manager
+    
+    For details on the expected behavior of the operations and their parameters 
+    refer to :rfc:`4741`.
+
+    Manager instances are also context managers so you can use it like this::
+
+        with manager.connect("host") as m:
+            # do your stuff
+    
+    ... or like this::
+    
+        m = manager.connect("host")
+        try:
+            # do your stuff
+        finally:
+            m.close()
+    
+    .. method:: get_config(source[, filter=None])
+        
+        Retrieve all or part of a specified configuration.
+        
+        :param source: name of the configuration datastore being queried
+        :type source: `string`
+        
+        :param filter: see :ref:`filter_params`
+    
+    .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
+        
+        Loads all or part of a specified configuration to the specified target configuration.
+        
+        The ``"rollback-on-error"`` *error_option* depends on the ``:rollback-on-error`` capability.
+        
+        :param target: name of the configuration datastore being edited
+        :type target: `string`
+        
+        :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
+        :type default_operation: `string`
+        
+        :param test_option: one of { ``"test_then_set"``, ``"set"`` }
+        :type test_option: `string`
+        
+        :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
+        :type error_option: `string`
+        
+        :param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object
+    
+    .. method:: copy_config(source, target)
+        
+        Create or replace an entire configuration datastore with the contents of
+        another complete configuration datastore. 
+        
+        :param source: see :ref:`srctarget_params`
+        
+        :param target: see :ref:`srctarget_params`
+    
+    .. method:: delete_config(target)
+        
+        Delete a configuration datastore.
+        
+        :param target: see :ref:`srctarget_params`
+    
+    .. method:: lock(target)
+        
+        Allows the client to lock the configuration system of a device.
+        
+        :param target: name of the configuration datastore to lock
+        :type target: `string`
+        
+    .. method:: unlock(target)
+    
+        Release a configuration lock, previously obtained with the
+        :meth:`~ncclient.manager.Manager.lock` operation.
+        
+        :param target: name of the configuration datastore to unlock
+        :type target: `string`
+    
+    .. method:: locked(target)
+        
+        Returns a context manager for a lock on a datastore, e.g.::
+        
+            with m.locked("running"):
+                # do your stuff
+
+        ... instead of::
+        
+            m.lock("running")
+            try:
+                # do your stuff
+            finally:
+                m.unlock("running")
+        
+        :param target: datastore name. See :ref:`srctarget_params`
+        
+        :rtype: `~ncclient.operations.LockContext`
+    
+    .. method:: get([filter=None])
+        
+        Retrieve running configuration and device state information.
+        
+        :param filter: see :ref:`filter_params`
+    
+    .. method:: close_session()
+        
+        Request graceful termination of the NETCONF session, and also close the
+        transport.
+    
+    .. method:: kill_session(session_id)
+        
+        Force the termination of a NETCONF session (not the current one!).
+        
+        :param session_id: session identifier of the NETCONF session to be
+                            terminated
+        :type session_id: `string`
+    
+    .. attribute:: async_mode
+        
+        Specify whether operations are executed asynchronously (:const:`True`)
+        or synchronously (:const:`False`) (the default).
+    
+    .. attribute:: raise_mode
+        
+        The raise *mode* affects what errors are raised as
+        :exc:`~ncclient.operations.RPCError` exceptions.
+        
+        * ``"all"`` -- any kind of *rpc-error* (error or warning)
+        * ``"errors"`` -- where the *error-type* attribute says it is an error
+        * ``"none"`` -- neither
+        
+    .. attribute:: client_capabilities
+    
+        `~ncclient.capabilities.Capabilities` object representing the client's
+        capabilities.
+    
+    .. attribute:: server_capabilities
+    
+        `~ncclient.capabilities.Capabilities` object representing the server's
+        capabilities.
+    
+    .. attribute:: session_id
+    
+        The *session-id* assigned by the NETCONF server.
+    
+    .. attribute:: connected
+        
+        A boolean value indicating whether currently connected to the NETCONF
+        server.
+
+
+Special kinds of parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To keep the API clean, some parameters can take on different types.
+
+.. _srctarget_params:
+
+Source and target parameters
+""""""""""""""""""""""""""""
+
+Where an method takes a *source* or *target* argument, usually a datastore name
+or URL is expected. The latter depends on the ``:url`` capability and on whether
+the specific URL scheme is supported. Either must be specified as a `string`.
+For example, ``"running"``, ``"ftp://user:pass@host/config"``.
+
+If the source may be a *<config>* element, e.g. as allowed for the *validate*
+RPC, it can be specified either as an XML string or an
+`~xml.etree.ElementTree.Element` object rooted in the *<config>* element.
+
+.. _filter_params:
+
+Filter parameters
+"""""""""""""""""
+
+Where a method takes a *filter* argument, it can take on the following types:
+
+* A ``tuple`` of *(type, criteria)*.
+    
+    Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
+    
+    * For ``"xpath"`` the *criteria* should be a `string` containing the XPath
+      expression.
+    * For ``"subtree"`` the *criteria* should be an XML string or an
+      `~xml.etree.ElementTree.Element` object containing the criteria.
+
+* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element`
+  object.
