doc update: reorganize chapters/files

1 files changed, 8 insertions, 279 deletions

diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index 85dd53a..005eeda 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -47,10 +47,10 @@ Native ports
         :param bool dsrdtr:
             Enable hardware (DSR/DTR) flow control.
 
-        :param float write_timeout
+        :param float write_timeout:
             Set a write timeout value.
 
-        :param float inter_byte_timeout
+        :param float inter_byte_timeout:
             Inter-character timeout, :const:`None` to disable (default).
 
         :exception ValueError:
@@ -890,17 +890,6 @@ Module functions and attributes
 
 .. function:: device(number)
 
-    :param number: Port number.
-    :return: String containing device name.
-    :deprecated: Use device names directly.
-
-    Convert a port number to a platform dependent device name. Unfortunately
-    this does not work well for all platforms; e.g. some may miss USB-Serial
-    converters and enumerate only internal serial ports.
-
-    The conversion may be made off-line, that is, there is no guarantee that
-    the returned device name really exists on the system.
-
     .. versionchanged:: 3.0 removed, use ``serial.tools.list_ports`` instead
 
 
@@ -913,7 +902,7 @@ Module functions and attributes
     Get a native or a :rfc:`2217` implementation of the Serial class, depending
     on port/url. This factory function is useful when an application wants
     to support both, local ports and remote ports. There is also support
-    for other types, see :ref:`URL <URLs>` section below.
+    for other types, see :ref:`URL <URLs>` section.
 
     The port is not opened when a keyword parameter called *do_not_open* is
     given and true, by default it is opened.
@@ -967,190 +956,15 @@ Module functions and attributes
     .. versionadded:: 3.0
 
 
-.. _URLs:
-
-URLs
-----
-The function :func:`serial_for_url` accepts the following types of URLs:
-
-- ``rfc2217://<host>:<port>[?<option>[&<option>...]]``
-- ``socket://<host>:<port>[?logging={debug|info|warning|error}]``
-- ``loop://[?logging={debug|info|warning|error}]``
-- ``hwgrep://<regexp>``
-- ``spy://port[?option[=value][&option[=value]]]``
-
-.. versionchanged:: 3.0 Options are specified with ``?`` and ``&`` instead of ``/``
-
-Device names are also supported, e.g.:
-
-- ``/dev/ttyUSB0`` (Linux)
-- ``COM3`` (Windows)
-
-Future releases of pySerial might add more types. Since pySerial 2.6 it is also
-possible for the user to add protocol handlers using
-:attr:`protocol_handler_packages`.
-
-``rfc2217://``
-    Used to connect to :rfc:`2217` compatible servers. All serial port
-    functions are supported. Implemented by :class:`rfc2217.Serial`.
-
-    Supported options in the URL are:
-
-    - ``ign_set_control`` does not wait for acknowledges to SET_CONTROL. This
-      option can be used for non compliant servers (i.e. when getting an
-      ``remote rejected value for option 'control'`` error when connecting).
-
-    - ``poll_modem``: The client issues NOTIFY_MODEMSTATE requests when status
-      lines are read (CTS/DTR/RI/CD). Without this option it relies on the server
-      sending the notifications automatically (that's what the RFC suggests and
-      most servers do). Enable this option when :attr:`cts` does not work as
-      expected, i.e. for servers that do not send notifications.
-
-    - ``timeout=<value>``: Change network timeout (default 3 seconds). This is
-      useful when the server takes a little more time to send its answers. The
-      timeout applies to the initial Telnet / :rfc:`2271` negotiation as well
-      as changing port settings or control line change commands.
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.rfc2217`` 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
-    connect to TCP/IP to serial port converters that do not support :rfc:`2217`.
-
-    Uses a TCP/IP socket. All serial port settings, control and status lines
-    are ignored. Only data is transmitted and received.
-
-    Supported options in the URL are:
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.socket`` 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).
-
-``loop://``
-    The least useful type. It simulates a loop back connection
-    (``RX<->TX``  ``RTS<->CTS``  ``DTR<->DSR``). It could be used to test
-    applications or run the unit tests.
-
-    Supported options in the URL are:
-
-    - ``logging={debug|info|warning|error}``: Prints diagnostic messages (not
-      useful for end users). It uses the logging module and a logger called
-      ``pySerial.loop`` 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).
-
-``hwgrep://``
-    This type uses :mod:`serial.tools.list_ports` to obtain a list of ports and
-    searches the list for matches by a regexp (see :py:mod:`re`) that follows
-    the slashes.
-
-    Depending on the capabilities of the list_ports module on the system, it is
-    possible to search for the description or hardware ID of a device, e.g. USB
-    VID:PID or texts.
-
-    Unfortunately, on some systems list_ports only lists a subset of the port
-    names with no additional information. Currently, on Windows and Linux and
-    OSX it should find additional information.
-
-``spy://``
-    Wrapping the native serial port, this protocol makes it possible to
-    intercept the data received and transmitted as well as the access to the
-    control lines, break and flush commands.
-
-    Supported options in the URL are:
-
-    - ``file=FILENAME`` output to given file or device instead of stderr
-    - ``color`` enable ANSI escape sequences to colorize output
-    - ``raw`` output the read and written data directly (default is to create a
-      hex dump). In this mode, no control line and other commands are logged.
-    - ``all`` also show ``in_waiting`` and empty ``read()`` calls (hidden by
-      default because of high traffic).
-
-    Example::
-
-        import serial
-
-        with serial.serial_for_url('spy:///dev/ttyUSB0?file=test.txt', timeout=1) as s:
-            s.dtr = False
-            s.write('hello world')
-            s.read(20)
-            s.dtr = True
-            s.write(serial.to_bytes(range(256)))
-            s.read(400)
-            s.send_break()
-
-        with open('test.txt') as f:
-            print(f.read())
-
-    Outputs::
-
-        000000.002 Q-RX reset_input_buffer
-        000000.002 DTR  inactive
-        000000.002 TX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
-        000001.015 RX   0000  68 65 6C 6C 6F 20 77 6F  72 6C 64                 hello world     
-        000001.015 DTR  active
-        000001.015 TX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
-        000001.015 TX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
-        000001.015 TX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
-        000001.015 TX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
-        000001.015 TX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
-        000001.016 TX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
-        000001.016 TX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
-        000001.016 TX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
-        000001.016 TX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
-        000001.016 TX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
-        000001.016 TX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
-        000001.016 TX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
-        000001.016 TX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
-        000001.016 TX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
-        000001.016 TX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
-        000001.016 TX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
-        000002.284 RX   0000  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F  ................
-        000002.284 RX   0010  10 11 12 13 14 15 16 17  18 19 1A 1B 1C 1D 1E 1F  ................
-        000002.284 RX   0020  20 21 22 23 24 25 26 27  28 29 2A 2B 2C 2D 2E 2F   !"#$%&'()*+,-./
-        000002.284 RX   0030  30 31 32 33 34 35 36 37  38 39 3A 3B 3C 3D 3E 3F  0123456789:;<=>?
-        000002.284 RX   0040  40 41 42 43 44 45 46 47  48 49 4A 4B 4C 4D 4E 4F  @ABCDEFGHIJKLMNO
-        000002.284 RX   0050  50 51 52 53 54 55 56 57  58 59 5A 5B 5C 5D 5E 5F  PQRSTUVWXYZ[\]^_
-        000002.284 RX   0060  60 61 62 63 64 65 66 67  68 69 6A 6B 6C 6D 6E 6F  `abcdefghijklmno
-        000002.284 RX   0070  70 71 72 73 74 75 76 77  78 79 7A 7B 7C 7D 7E 7F  pqrstuvwxyz{|}~.
-        000002.284 RX   0080  80 81 82 83 84 85 86 87  88 89 8A 8B 8C 8D 8E 8F  ................
-        000002.284 RX   0090  90 91 92 93 94 95 96 97  98 99 9A 9B 9C 9D 9E 9F  ................
-        000002.284 RX   00A0  A0 A1 A2 A3 A4 A5 A6 A7  A8 A9 AA AB AC AD AE AF  ................
-        000002.284 RX   00B0  B0 B1 B2 B3 B4 B5 B6 B7  B8 B9 BA BB BC BD BE BF  ................
-        000002.284 RX   00C0  C0 C1 C2 C3 C4 C5 C6 C7  C8 C9 CA CB CC CD CE CF  ................
-        000002.284 RX   00D0  D0 D1 D2 D3 D4 D5 D6 D7  D8 D9 DA DB DC DD DE DF  ................
-        000002.284 RX   00E0  E0 E1 E2 E3 E4 E5 E6 E7  E8 E9 EA EB EC ED EE EF  ................
-        000002.284 RX   00F0  F0 F1 F2 F3 F4 F5 F6 F7  F8 F9 FA FB FC FD FE FF  ................
-        000002.284 BRK  send_break 0.25
-
-    .. versionadded:: 3.0
-
-
-
-Examples:
-
-- ``rfc2217://localhost:7000``
-- ``rfc2217://localhost:7000?poll_modem``
-- ``rfc2217://localhost:7000?ign_set_control&timeout=5.5``
-- ``socket://localhost:7777``
-- ``loop://?logging=debug``
-- ``hwgrep://0451:f432`` (USB VID:PID)
-- ``spy://COM54?file=log.txt``
-
-
 asyncio
 =======
 
+.. module:: serial.aio
+
 .. warning:: This implementation is currently in an experimental state. Use
     at your own risk.
 
-Experimental asyncio support is available for Python 3.4 and newer. The
+Experimental asyncio support is available for Python 3.4 and newer. The module
 :mod:`serial.aio` provides a :class:`asyncio.Transport`:
 ``SerialTransport``.
 
@@ -1173,7 +987,7 @@ Example::
         def connection_made(self, transport):
             self.transport = transport
             print('port opened', transport)
-            transport.serial.setRTS(0)
+            transport.serial.rts = False
             transport.write(b'hello world\n')
 
         def data_received(self, data):
@@ -1185,93 +999,8 @@ Example::
             asyncio.get_event_loop().stop()
 
     loop = asyncio.get_event_loop()
-    coro = create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
+    coro = serial.aio.create_serial_connection(loop, Output, '/dev/ttyUSB0', baudrate=115200)
     loop.run_until_complete(coro)
     loop.run_forever()
     loop.close()
 
-
-Tools
-=====
-
-serial.tools.list_ports
------------------------
-.. module:: serial.tools.list_ports
-.. versionadded:: 2.6
-
-This module can be executed to get a list of ports (``python -m
-serial.tools.list_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 in human readable form
-    - sort of hardware ID. 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. Also note that the reported strings are different across platforms
-    and operating systems, even for the same device.
-
-    .. 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: OSX (iokit)
-    :platform: Windows (setupapi, registry)
-
-
-.. function:: grep(regexp)
-
-    :param regexp: regular expression (see stdlib :mod:`re`)
-    :return: filtered sequence, see :func:`comports`.
-
-    Search for ports using a regular expression. Port name, description and
-    hardware ID are searched (case insensitive). The function returns an
-    iterable that contains the same tuples that :func:`comport` generates but
-    only those that match the regexp.
-
-
-Command line usage
-
-Help for ``python -m serial.tools.list_ports``::
-
-    usage: list_ports.py [-h] [-v] [-q] [-n N] [regexp]
-
-    Serial port enumeration
-
-    positional arguments:
-      regexp         only show ports that match this regex
-
-    optional arguments:
-      -h, --help     show this help message and exit
-      -v, --verbose  show more messages
-      -q, --quiet    suppress all messages
-      -n N           only output the N-th entry
-
-Examples:
-
-- List all ports with details::
-
-    python -m serial.tools.list_ports -v
-
-- List the 2nd port matching a USB VID:PID pattern::
-
-    python -m serial.tools.list_ports 1234:5678 -q -n 2
-
-
-serial.tools.miniterm
----------------------
-.. module:: serial.tools.miniterm
-.. versionadded:: 2.6
-
-Miniterm is now available as module instead of example.
-see :ref:`miniterm` for details.
-