doc update (serial.tools), links to standard library now go to docs.python.org

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

3 files changed, 69 insertions, 29 deletions

diff --git a/documentation/conf.py b/documentation/conf.py
index 7fb30b0..af724a5 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -22,7 +22,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -192,3 +192,9 @@ latex_logo = 'pyserial.png'
 
 # If false, no module index is generated.
 #latex_use_modindex = True
+
+# for external links to standard library
+intersphinx_mapping = {
+        #~ 'python': ('http://docs.python.org', None),
+        'py': ('http://docs.python.org', None),
+        }
diff --git a/documentation/examples.rst b/documentation/examples.rst
index 6f0fcf0..39f238c 100644
--- a/documentation/examples.rst
+++ b/documentation/examples.rst
@@ -300,27 +300,6 @@ enhancedserial.py_
 .. _enhancedserial.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/enhancedserial.py
 
 
-Finding serial ports
-====================
-scan.py_
-    A simple loop that probes serial ports by number.
-
-scanlinux.py_
-    A Linux only version looking at the entries in ``/dev``. It works best with
-    on systems with devfs or udev that only create those entries that represent
-    devices. On older installations a lot of pre-created device files are found
-    and an additional open check should be added to ensure that the device is
-    real.
-
-scanwin32.py_
-    A Windows only version that returns a list of serial ports with information
-    from the registry.
-
-.. _scan.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scan.py
-.. _scanlinux.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanlinux.py
-.. _scanwin32.py: http://pyserial.svn.sourceforge.net/viewvc/*checkout*/pyserial/trunk/pyserial/examples/scanwin32.py
-
-
 Unit tests
 ==========
 The project uses a number of unit test to verify the functionality. They all
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index d57d192..b06490f 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -384,18 +384,18 @@ Native ports
 
 .. note::
 
-    For systems that provide the :mod:`io` library (Python 2.6 and newer), the
-    class :class:`Serial` will derive from :class:`io.RawIOBase`. For all
+    For systems that provide the :py:mod:`io` library (Python 2.6 and newer), the
+    class :class:`Serial` will derive from :py:class:`io.RawIOBase`. For all
     others from :class:`FileLike`.
 
-    Implementation detail: some attributes and functions are provided by the
-    class :class:`SerialBase` and some by the platform specific class and
-    others by the base class mentioned above.
+Implementation detail: some attributes and functions are provided by the
+class :class:`SerialBase` and some by the platform specific class and
+others by the base class mentioned above.
 
 .. class:: FileLike
 
     An abstract file like class. It is used as base class for :class:`Serial`
-    when no :mod:`io` module is available.
+    when no :py:mod:`io` module is available.
 
     This class implements :meth:`readline` and :meth:`readlines` based on
     :meth:`read` and :meth:`writelines` based on :meth:`write`.
@@ -475,7 +475,7 @@ Native ports
 
     .. method:: readlines(sizehint=None, eol='\\n')
 
-        :param size: Ignored parameter.
+        :param sizehint: Ignored parameter.
         :param eol: The end of line character.
 
         Read a list of lines, until timeout. *sizehint* is ignored and only
@@ -850,3 +850,58 @@ Examples:
 - ``rfc2217://localhost:7000/ign_set_control/timeout=5.5``
 - ``socket://localhost:7777``
 - ``loop://logging=debug``
+
+Tools
+=====
+
+
+serial.tools.list_ports
+-----------------------
+.. module:: serial.tools.list_ports
+.. versionadded:: 2.6
+
+This module can be executed (``python -m serial.tools.list_ports``) to get a
+list of ports. It also contains the following functions.
+
+
+.. function:: comports()
+
+    :return: an iterable.
+
+    The function returns an iterable that yields tuples of three strings:
+
+    - port name: as it can be passed to :class:`serial.Serial` or
+      :func:`serial.serial_for_url`
+    - description: human readable text identifying the port
+    - hardware id: some sort of hardware identification. E.g. may contain
+      VID:PID of USB-serial adapters.
+
+    Items are returned in no particular order. It may make sense to sort the items.
+
+    .. note:: Support is limited to a number of operating systems. On some
+              systems description and hardware id will not be available
+              (``None``).
+
+    :platform: Posix (/dev files)
+    :platform: Linux (/dev files, sysfs and lsusb)
+    :platform: Windows (setupapi, registry)
+
+
+.. function:: grep(regexp)
+
+    :param regexp: regular expression (see stdlib :mod:`re`)
+    :return: see :func:`comports`.
+
+    Search for ports using a regular expression. Port name, description and
+    hardware ID are searched. The function returns an iterable that returns the
+    same tuples as comport() would do.
+
+
+serial.tools.miniterm
+-----------------------
+.. module:: serial.tools.miniterm
+.. versionadded:: 2.6
+
+Miniterm is now available as module instead of example.
+see :ref:`miniterm` for details.
+