Repaired documentation, included changelog in docs.

.github/workflows/release.yml

@@ -1,10 +1,8 @@
 name: release
 
 on:
-  push:
-    branches:
-      - "main"
-      - "master"
+  workflow_dispatch:
+
 
 jobs:
   pypi_version:

CHANGELOG.md

@@ -1,21 +1,27 @@
-# Changelog
+Changelog
+=========
 
 ## Unpublished
 
 ### Upgrade steps
 
+- Implementations that use the `Driver` class directly must update their code
+  with respect to handling received data and retrieving messages.
+  Use `Driver.receive()` to receive data and add it to the internal buffer.
+  Use `Driver.get()` to obtain the next message.
+
 ### Breaking Changes
 
 - Removed support for Python version 3.6 and lower.
+- `Driver.receive()` no longer returns a list of messages.
+  Instead, use `Driver.get()` to retrieve the next message.
 
 ### New Features
 
 ### Bug Fixes
 
 ### Improvements
 
-- Added `block` and `timeout` arguments to the `Driver.get()` method.
-
 ### Other Changes
 
 - Converted project to use `hatch`.
@@ -37,6 +43,7 @@
 
 - Updated documentation and examples
 
+
 ## v0.5.0
 
 ### New Features

README.rst → README.md

@@ -1,106 +1,82 @@
-
-.. image:: https://readthedocs.org/projects/sliplib/badge/?version=latest
-   :target: http://sliplib.readthedocs.org/en/master/?badge=master
-   :alt: ReadTheDocs Documentation Status
-
-.. image:: https://travis-ci.org/rhjdjong/SlipLib.svg
-   :target: https://travis-ci.org/rhjdjong/SlipLib
-   :alt: Travis Test Status
-
-.. image:: https://ci.appveyor.com/api/projects/status/d1nwwn34xoaxh3tt/branch/master?svg=true
-   :target: https://ci.appveyor.com/project/RuuddeJong/sliplib/branch/master
-   :alt: AppVeyor Test Status
-
-
-==============================================
-``sliplib`` --- A module for the SLIP protocol
-==============================================
-
-
-The `sliplib` module implements the encoding and decoding
-functionality for SLIP packets, as described in :rfc:`1055`.
-It defines encoding, decoding, and validation functions,
-as well as a  driver class that can be used to implement
-a SLIP protocol stack, and higher-level classes that
-apply the SLIP protocol to TCP connections or IO streams.
-Read the `documentation <http://sliplib.readthedocs.org/en/master/>`_
-for detailed information.
-
-Background
-==========
-
-The SLIP protocol is described in :rfc:`1055` (:title:`A Nonstandard for
-Transmission of IP Datagrams over Serial Lines: SLIP`, J. Romkey,
-June 1988).  The original purpose of the protocol is
-to provide a mechanism to indicate the boundaries of IP packets,
-in particular when the IP packets are sent over a connection that
-does not provide a framing mechanism, such as serial lines or
-dial-up connections.
-
-There is, however, nothing specific to IP in the SLIP protocol.
-SLIP offers a generic framing method that can be used for any
-type of data that must be transmitted over a (continuous) byte stream.
-In fact, the main reason for creating this module
-was the need to communicate with a third-party application that
-used SLIP over TCP (which is a continuous byte stream)
-to frame variable length data structures.
-
-
-Usage
-=====
-
-Installation
-------------
-
-To install the `sliplib` module, use
-
-.. code::
-
-    pip install sliplib
-
-Low-level usage
----------------
-
-The recommended basic usage is to run all encoding and decoding operations
-through an instantiation `driver` of the `Driver` class, in combination
-with the appropriate I/O code.
-The `Driver` class itself works without any I/O, and can therefore be used with
-any networking code, or any bytestream like pipes, serial I/O, etc.
-It can work in synchronous as well as in asynchronous environments.
-
-The `Driver` class offers the methods
-`send` and `receive` to handle
-the conversion between messages and SLIP-encoded packets.
-
-High-level usage
-----------------
-
-The module also provides a `SlipWrapper` abstract baseclass
-that provides the methods `send_msg` and `recv_msg` to send
-and receive single SLIP-encoded messages. This base class
-wraps an instance of the `Driver` class with a user-provided stream.
-
-Two concrete subclasses of `SlipWrapper` are provided:
-
-* `SlipStream` allows the wrapping of a byte IO stream.
-* `SlipSocket` allows the wrapping of a TCP socket.
-
-In addition, the module also provides a `SlipRequestHandler`
-to facilitate the creation of TCP servers that can handle
-SLIP-encoded messages.
-
-
-Error Handling
-==============
-
-Contrary to the reference implementation described in :rfc:`1055`,
-which chooses to essentially ignore protocol errors,
-the functions and classes in the `sliplib` module
-use a `ProtocolError` exception
-to indicate protocol errors, i.e. SLIP packets with invalid byte sequences.
-The `Driver` class raises the `ProtocolError` exception
-as soon as a complete SLIP packet with an invalid byte sequence is received.
-The `SlipWrapper` class and its subclasses catch the `ProtocolError`\s
-raised by the `Driver` class, and re-raise them when
-an attempt is made to read the contents of a SLIP packet that contained
-invalid data.
+# ``sliplib`` --- A module for the SLIP protocol
+
+The `sliplib` module implements the encoding and decoding
+functionality for SLIP packets, as described in
+[RFC 1055][rfc1055].
+It defines encoding, decoding, and validation functions,
+as well as a  driver class that can be used to implement
+a SLIP protocol stack, and higher-level classes that
+apply the SLIP protocol to TCP connections or IO streams.
+Read the [documentation](http://sliplib.readthedocs.org/en/master/)
+for detailed information.
+
+## Background
+
+The SLIP protocol is described in [RFC 1055][rfc1055] (*A Nonstandard for
+Transmission of IP Datagrams over Serial Lines: SLIP*, J. Romkey,
+June 1988).  The original purpose of the protocol is
+to provide a mechanism to indicate the boundaries of IP packets,
+in particular when the IP packets are sent over a connection that
+does not provide a framing mechanism, such as serial lines or
+dial-up connections.
+
+There is, however, nothing specific to IP in the SLIP protocol.
+SLIP offers a generic framing method that can be used for any
+type of data that must be transmitted over a (continuous) byte stream.
+In fact, the main reason for creating this module
+was the need to communicate with a third-party application that
+used SLIP over TCP (which is a continuous byte stream)
+to frame variable length data structures.
+
+
+## Usage
+
+### Installation
+
+To install the `sliplib` module, use
+
+```
+pip install sliplib
+```
+
+### Low-level usage
+
+The recommended basic usage is to run all encoding and decoding operations
+through an instantiation `driver` of the `Driver` class, in combination
+with the appropriate I/O code.
+The `Driver` class itself works without any I/O, and can therefore be used with
+any networking code, or any bytestream like pipes, serial I/O, etc.
+It can work in synchronous as well as in asynchronous environments.
+
+The `Driver` class offers the methods
+`send` and `receive` to handle
+the conversion between messages and SLIP-encoded packets.
+
+### High-level usage
+
+The module also provides a `SlipWrapper` abstract baseclass
+that provides the methods `send_msg` and `recv_msg` to send
+and receive single SLIP-encoded messages. This base class
+wraps an instance of the `Driver` class with a user-provided stream.
+
+Two concrete subclasses of `SlipWrapper` are provided:
+
+* `SlipStream` allows the wrapping of a byte IO stream.
+* `SlipSocket` allows the wrapping of a TCP socket.
+
+In addition, the module also provides a `SlipRequestHandler`
+to facilitate the creation of TCP servers that can handle
+SLIP-encoded messages.
+
+
+## Error Handling
+
+Contrary to the reference implementation described in :rfc:`1055`,
+which chooses to essentially ignore protocol errors,
+the functions and classes in the `sliplib` module
+use a `ProtocolError` exception
+to indicate protocol errors, i.e. SLIP packets with invalid byte sequences.
+The `Driver` class raises a `ProtocolError` exception
+when an attempt is made to `get()` a message from such a packet.
+
+[rfc1055]: http://tools.ietf.org/html/rfc1055.html

docs/source/changes.md

@@ -0,0 +1,2 @@
+```{include} ../../CHANGELOG.md
+```

docs/source/conf.py

@@ -40,18 +40,20 @@
     "sphinx_toolbox.more_autodoc.typevars",
     "sphinx_toolbox.more_autodoc.variables",
     "sphinx_autodoc_typehints",
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = []
 
 napoleon_google_docstring = True
-# napoleon_use_rtype = False
 autoclass_content = "both"
 autodoc_typehints = "description"
 autodoc_type_aliases = {}
 add_module_names = False
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -7,15 +7,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. include:: ../../README.rst
-.. include:: ../../CHANGES.rst
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
    module
    example
+   changes
 
 
 Indices and tables

examples/echoserver/__init__.py

@@ -76,23 +76,26 @@
 By running the server with the argument ``ipv6``,
 an IPv6-based connection will be established.
 
-In the server terminal window:
-
-.. code:: bash
-
-   $ python server.py ipv6
-   Slip server listening on localhost, port 59454
-   Incoming connection from ('::1', 59458, 0, 0)
-   ...
-
-In the client terminal window:
-
-.. code:: bash
-
-   $ python client.py 59454
-   Connecting to server on port 59454
-   Connected to ('::1', 59454, 0, 0)
-   Message>
-   ...
-
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Server
+     - Client
+   * - .. code:: bash
+
+          $ python server.py ipv6
+          Slip server listening on localhost, port 59454
+          \u200B
+          Incoming connection from ('::1', 59458, 0, 0)
+          \u200B
+          ...
+     - .. code:: bash
+
+          \u200B
+          \u200B
+          $ python client.py 59454
+          Connecting to server on port 59454
+          Message>
+          ...
 """

pyproject.toml

@@ -132,6 +132,7 @@ include = [
 [tool.hatch.envs.doc]
 python = "3.12"
 dependencies = [
+    "myst-parser",
     "sphinx",
     "sphinx_rtd_theme",
     "sphinx-toolbox",

src/sliplib/__init__.py

@@ -13,22 +13,6 @@
 as well as various classes that can be used to to wrap
 the SLIP protocol over different kinds of byte streams.
 
-The SLIP protocol is described in :rfc:`1055` (:title:`A Nonstandard for
-Transmission of IP Datagrams over Serial Lines: SLIP`, J. Romkey,
-June 1988).  The original purpose of the protocol is
-to provide a mechanism to indicate the boundaries of IP packets,
-in particular when the IP packets are sent over a connection that
-does not provide a framing mechanism, such as serial lines or
-dial-up connections.
-
-There is, however, nothing specific to IP in the SLIP protocol.
-The protocol describes a generic framing method that can be used for any
-type of data that must be transmitted over a (continuous) byte stream.
-In fact, the main reason for creating this module
-was the need to communicate with a third-party application that
-used SLIP over TCP (which is a continuous byte stream)
-to frame variable length data structures.
-
 The SLIP protocol uses four special byte values:
 
 =============== ================ =============================================
@@ -41,16 +25,16 @@
 =============== ================ =============================================
 
 An :const:`END` byte in the message is encoded as the sequence
-:code:`ESC+ESC_END` (:code:`b'\\xdb\\xdc'`)
+:const:`ESC+ESC_END` (:code:`b'\\\\xdb\\\\xdc'`)
 in the slip packet,
 and an :const:`ESC` byte  in the message is encoded
-as the sequence :code:`ESC+ESC_ESC` (:code:`b'\\xdb\\xdd'`).
+as the sequence :const:`ESC+ESC_ESC` (:code:`b'\\\\xdb\\\\xdd'`).
 
 .. csv-table::
    :header: "Decoded", "Encoded"
 
-   :code:`b'\\xc0'`, :code:`b'\\xdb\\xdc'`
-   :code:`b'\\xdb'`, :code:`b'\\xdb\\xdd'`
+   :code:`b'\\\\xc0'`, :code:`b'\\\\xdb\\\\xdc'`
+   :code:`b'\\\\xdb'`, :code:`b'\\\\xdb\\\\xdd'`
 
 As a consequence, an :const:`ESC` byte in an encoded SLIP packet
 must always be followed by an :const:`ESC_END` or an :const:`ESC_ESC` byte;