- update docs

- remove "critical" from log level choices in URL


git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@339 f19166aa-fa4f-0410-85c2-fa1106f25c8a

3 files changed, 50 insertions, 4 deletions

diff --git a/documentation/appendix.rst b/documentation/appendix.rst
index 001c6e5..8492717 100644
--- a/documentation/appendix.rst
+++ b/documentation/appendix.rst
@@ -2,6 +2,38 @@
  Appendix
 ==========
 
+How To
+======
+
+Enable :rfc:`2217` in programs using pySerial.
+    Patch the code where the :class:`serial.Serial` is instantiated. Replace
+    it with::
+
+        try:
+            s = serial.serial_for_url(...)
+        except AttributeError:
+            s = serial.Serial(...)
+
+    Assuming the application already stores port names as strings that's all
+    that is required. The user just needs a way to change the port setting of
+    your application to an ``rfc2217://`` :ref:`URL <URLs>` (e.g. by editing a
+    configuration file, GUI dialog etc.).
+
+    Please note that this enables all :ref:`URL <URLs>` types supported by
+    pySerial and that those involving the network are unencrypted and not
+    protected against eavesdropping.
+
+Test your setup.
+    Is the device not working as expected? Maybe it's time to check the
+    connection before proceeding. :ref:`miniterm` from the :ref:`examples`
+    can be used to open the serial port and do some basic tests.
+
+    To test cables, connecting RX to TX (loop back) and typing some characters
+    in :ref:`miniterm` is a simple test. When the characters are displayed
+    on the screen, then at least RX and TX work (they still could be swapped
+    though).
+
+
 Related software
 ================
 
diff --git a/documentation/examples.rst b/documentation/examples.rst
index 429f86a..0bfdaae 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -1,7 +1,11 @@
+.. _examples:
+
 ==========
  Examples
 ==========
 
+.. _miniterm:
+
 Miniterm
 ========
 This is a console application that provides a small terminal application.
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index e634de3..70ff78f 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -569,7 +569,8 @@ Native ports
         :param serial_port: a :class:`Serial` instance that is managed.
         :param connection: an object implementing :meth:`write`, used to write
             to the network.
-        :param debug_output: used for development please set for False
+        :param debug_output: enables debug messages: a :class:`logging.Logger`
+            instance or None.
 
         Initializes the Manager and starts negotiating with client in Telnet
         and :rfc:`2217` protocol. The negotiation starts immediately so that
@@ -586,6 +587,11 @@ Native ports
         raw form (:meth:`escape` must not be used) as it is used to send Telnet
         and :rfc:`2217` control commands.
 
+        For diagnostics of the connection or the implementation, *debug_output*
+        can be set to an instance of a :class:`logging.Logger` (e.g.
+        ``logging.getLogger('rfc2217.server')``). The caller should configure
+        the logger using ``setLevel`` for the desired detail level of the logs.
+
     .. method:: escape(data)
 
         :param data: data to be sent over the network.
@@ -700,7 +706,7 @@ Functions:
 
 .. function:: serial_for_url(url, \*args, \*\*kwargs)
 
-    :param url: Device name, number or URL_
+    :param url: Device name, number or :ref:`URL <URLs>`
     :param do_not_open: When set to true, the serial port is not opened.
     :return: an instance of :class:`Serial` or a compatible object.
 
@@ -717,7 +723,7 @@ Functions:
 
     .. versionadded:: 2.5
 
-.. _URL: URLs_
+.. _URLs:
 
 URLs
 ----
@@ -751,7 +757,11 @@ accept the following types URL:
       timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
       as changing port settings or control line change commands.
 
-    - ``debug``: Prints diagnostic messages (not useful for end users).
+    - ``logging=[debug|info|warning|error]``: Prints diagnostic messages (not
+      useful for end users). It uses the logging module so that the application
+      can setup up logging handlers etc. It will call
+      :meth:`logging.basicConfig` which initializes for output on
+      ``sys.stderr`` (if no logging was set up already).
 
 ``socket://``
     The purpose of this connection type is that applications using pySerial can