added "Creating a new interface/backend" section to the documentation pages

felixdivo · felixdivo · commit 51eae1c672bb · 2018-05-28T00:37:12.000+02:00
diff --git a/can/bus.py b/can/bus.py
@@ -22,37 +22,6 @@
 class BusABC(object):
     """The CAN Bus Abstract Base Class that serves as the basis
     for all concrete interfaces.
-
-    Concrete implementations *have to* implement the following:
-        * :meth:`~can.BusABC.send` to send individual messages
-        * :meth:`~can.BusABC._recv_internal` to receive individual messages
-          (see note below)
-        * set the :attr:`~can.BusABC.channel_info` attribute to a string describing
-          the underlying bus and/or channel
-
-    They *might* implement the following:
-        * :meth:`~can.BusABC.flush_tx_buffer` to allow discrading any
-          messages yet to be sent
-        * :meth:`~can.BusABC.shutdown` to override how the bus should
-          shut down
-        * :meth:`~can.BusABC.send_periodic` to override the software based
-          periodic sending and push it down to the kernel or hardware
-        * :meth:`~can.BusABC._apply_filters` to apply efficient filters
-          to lower level systems like the OS kernel or hardware
-        * :meth:`~can.BusABC._detect_available_configs` to allow the interface
-          to report which configurations are currently available for new
-          connections
-        * :meth:`~can.BusABC.state` property to allow reading and/or changing
-          the bus state
-
-    .. note::
-
-       Previously, concrete bus classes had to override :meth:`~can.BusABC.recv`
-       directly instead of :meth:`~can.BusABC._recv_internal`, but that has
-       changed to allow the abstract base class to handle in-software message
-       filtering as a fallback. Older (custom) interfaces might still be
-       implemented like that and thus might not provide message filtering.
-
     """
 
     #: a string describing the underlying bus and/or channel
@@ -150,7 +119,9 @@ def _recv_internal(self, timeout):
             over time for some interfaces, like for example in the Kvaser interface.
             Thus it cannot be simplified to a constant value.
 
-        :param float timeout: seconds to wait for a message
+        :param float timeout: seconds to wait for a message,
+                              see :meth:`can.BusABC.send`
+
         :rtype: tuple[can.Message, bool] or tuple[None, bool]
         :return:
             1.  a message that was read or None on timeout
diff --git a/doc/development.rst b/doc/development.rst
@@ -27,6 +27,55 @@ The following assumes that the commands are executed from the root of the reposi
   makes Sphinx complain about more subtle problems.
 
 
+Creating a new interface/backend
+--------------------------------
+
+These steps are a guideline on how to add a new backend to python-can.
+
+- Create a module (either a ``*.py`` or an entire subdirctory depending
+  on the complexity) inside ``can.interfaces``
+- Implement the central part of the backend: the bus class that extends
+  :class:`can.BusABC`. See below for more info on this one!
+- Register your backend bus class in ``can.interface.BACKENDS`` and
+  ``can.interfaces.VALID_INTERFACES``.
+- Add docs where appropiate, like in ``doc/interfaces.rst`` and add
+  an entry in ``doc/interface/*``.
+- Add tests in ``test/*`` where appropiate.
+
+About the ``BusABC`` class
+==========================
+
+Concrete implementations *have to* implement the following:
+    * :meth:`~can.BusABC.send` to send individual messages
+    * :meth:`~can.BusABC._recv_internal` to receive individual messages
+      (see note below)
+    * set the :attr:`~can.BusABC.channel_info` attribute to a string describing
+      the underlying bus and/or channel
+
+They *might* implement the following:
+    * :meth:`~can.BusABC.flush_tx_buffer` to allow discrading any
+      messages yet to be sent
+    * :meth:`~can.BusABC.shutdown` to override how the bus should
+      shut down
+    * :meth:`~can.BusABC.send_periodic` to override the software based
+      periodic sending and push it down to the kernel or hardware
+    * :meth:`~can.BusABC._apply_filters` to apply efficient filters
+      to lower level systems like the OS kernel or hardware
+    * :meth:`~can.BusABC._detect_available_configs` to allow the interface
+      to report which configurations are currently available for new
+      connections
+    * :meth:`~can.BusABC.state` property to allow reading and/or changing
+      the bus state
+
+.. note::
+
+    Previously, concrete bus classes had to override :meth:`~can.BusABC.recv`
+    directly instead of :meth:`~can.BusABC._recv_internal`, but that has
+    changed to allow the abstract base class to handle in-software message
+    filtering as a fallback. Older (custom) interfaces might still be
+    implemented like that and thus might not provide message filtering.
+
+
 Creating a Release
 ------------------
 
@@ -41,7 +90,7 @@ Creating a Release
 - Upload with twine ``twine upload dist/python-can-X.Y.Z*``
 - In a new virtual env check that the package can be installed with pip: ``pip install python-can==X.Y.Z``
 - Create a new tag in the repository.
-- Check the release on PyPi, readthedocs and github.
+- Check the release on PyPi, Read the Docs and GitHub.
 
 
 Code Structure
