From fe4578fc7f96ecf31fbc614ecb9ea432036f1661 Mon Sep 17 00:00:00 2001 From: cliechti Date: Thu, 25 Aug 2011 22:06:38 +0000 Subject: 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 --- documentation/conf.py | 8 ++++- documentation/examples.rst | 21 ------------- documentation/pyserial_api.rst | 69 +++++++++++++++++++++++++++++++++++++----- 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. + -- cgit v1.2.1