Fix Sphinx errors/warnings & Misc. cleanups

can/broadcastmanager.py

@@ -10,7 +10,6 @@
 
 import abc
 import logging
-
 import threading
 import time
 
@@ -20,7 +19,7 @@
 
 class CyclicTask(object):
     """
-    Abstract Base for all Cyclic Tasks
+    Abstract Base for all cyclic tasks.
     """
 
     @abc.abstractmethod
@@ -36,7 +35,7 @@ class CyclicSendTaskABC(CyclicTask):
 
     def __init__(self, message, period):
         """
-        :param message: The :class:`can.Message` to be sent periodically.
+        :param can.Message message: The message to be sent periodically.
         :param float period: The rate in seconds at which to send the message.
         """
         self.message = message
@@ -51,7 +50,7 @@ class LimitedDurationCyclicSendTaskABC(CyclicSendTaskABC):
     def __init__(self, message, period, duration):
         """Message send task with a defined duration and period.
 
-        :param message: The :class:`can.Message` to be sent periodically.
+        :param can.Message message: The message to be sent periodically.
         :param float period: The rate in seconds at which to send the message.
         :param float duration:
             The duration to keep sending this message at given rate.
@@ -76,19 +75,28 @@ def modify_data(self, message):
         """Update the contents of this periodically sent message without altering
         the timing.
 
-        :param message: The :class:`~can.Message` with new :attr:`can.Message.data`.
+        :param can.Message message:
+          The message with the new :attr:`can.Message.data`.
+          Note: The arbitration ID cannot be changed.
         """
         self.message = message
 
 
 class MultiRateCyclicSendTaskABC(CyclicSendTaskABC):
     """Exposes more of the full power of the TX_SETUP opcode.
-
-    Transmits a message `count` times at `initial_period` then
-    continues to transmit message at `subsequent_period`.
     """
 
     def __init__(self, channel, message, count, initial_period, subsequent_period):
+        """
+        Transmits a message `count` times at `initial_period` then continues to
+        transmit message at `subsequent_period`.
+
+        :param can.interface.Bus channel:
+        :param can.Message message:
+        :param int count:
+        :param float initial_period:
+        :param float subsequent_period:
+        """
         super(MultiRateCyclicSendTaskABC, self).__init__(channel, message, subsequent_period)
 
 
@@ -135,12 +143,14 @@ def _run(self):
 
 
 def send_periodic(bus, message, period, *args, **kwargs):
-    """Send a message every `period` seconds on the given channel.
+    """
+    Send a :class:`~can.Message` every `period` seconds on the given bus.
 
-    :param bus: The :class:`can.BusABC` to transmit to.
-    :param message: The :class:`can.Message` instance to periodically send
+    :param can.BusABC bus: A CAN bus which supports sending.
+    :param can.Message message: Message to send periodically.
+    :param float period: The minimum time between sending messages.
     :return: A started task instance
     """
     log.warning("The function `can.send_periodic` is deprecated and will " +
-             "be removed in version 2.3. Please use `can.Bus.send_periodic` instead.")
+                "be removed in version 2.3. Please use `can.Bus.send_periodic` instead.")
     return bus.send_periodic(message, period, *args, **kwargs)

can/bus.py

@@ -59,7 +59,7 @@ def recv(self, timeout=None):
         :param float timeout:
             seconds to wait for a message or None to wait indefinitely
 
-        :rtype: can.Message or None
+        :rtype: can.Message or NoneType
         :return:
             None on timeout or a :class:`can.Message` object.
         :raises can.CanError:
@@ -118,9 +118,9 @@ def _recv_internal(self, timeout):
             Thus it cannot be simplified to a constant value.
 
         :param float timeout: seconds to wait for a message,
-                              see :meth:`can.BusABC.send`
+                              see :meth:`~can.BusABC.send`
 
-        :rtype: tuple[can.Message, bool] or tuple[None, bool]
+        :rtype: tuple[can.Message, bool] or tuple[NoneType, bool]
         :return:
             1.  a message that was read or None on timeout
             2.  a bool that is True if message filtering has already
@@ -172,7 +172,7 @@ def send_periodic(self, msg, period, duration=None):
             Note the duration before the message stops being sent may not
             be exactly the same as the duration specified by the user. In
             general the message will be sent at the given rate until at
-            least *duration* seconds.
+            least **duration** seconds.
 
         """
         if not hasattr(self, "_lock_send_periodic"):

can/interfaces/iscan.py

@@ -36,7 +36,7 @@ def check_status(result, function, arguments):
 
 try:
     iscan = ctypes.cdll.LoadLibrary("iscandrv")
-except Exception as e:
+except OSError as e:
     iscan = None
     logger.warning("Failed to load IS-CAN driver: %s", e)
 else:

can/interfaces/pcan/pcan.py

@@ -5,16 +5,16 @@
 Enable basic CAN over a PCAN USB device.
 """
 
-from __future__ import absolute_import, print_function
+from __future__ import absolute_import, print_function, division
 
 import logging
 import sys
 import time
 
 import can
 from can import CanError, Message, BusABC
-from .PCANBasic import *
 from can.bus import BusState
+from .basic import *
 
 boottimeEpoch = 0
 try:
@@ -72,13 +72,13 @@ def __init__(self, channel, state=BusState.ACTIVE, *args, **kwargs):
         """A PCAN USB interface to CAN.
 
         On top of the usual :class:`~can.Bus` methods provided,
-        the PCAN interface includes the :meth:`~can.interface.pcan.PcanBus.flash()`
-        and :meth:`~can.interface.pcan.PcanBus.status()` methods.
+        the PCAN interface includes the :meth:`~can.interface.pcan.PcanBus.flash`
+        and :meth:`~can.interface.pcan.PcanBus.status` methods.
 
         :param str channel:
             The can interface name. An example would be 'PCAN_USBBUS1'
 
-        :param BusState state:
+        :param can.bus.BusState state:
             BusState of the channel.
             Default is ACTIVE
 
@@ -160,7 +160,8 @@ def status(self):
         """
         Query the PCAN bus status.
 
-        :return: The status code. See values in pcan_constants.py
+        :rtype: int
+        :return: The status code. See values in **basic.PCAN_ERROR_**
         """
         return self.m_objPCANBasic.GetStatus(self.m_PcanHandle)
 

can/util.py

@@ -190,10 +190,10 @@ def load_config(path=None, config=None):
     if 'bitrate' in config:
         config['bitrate'] = int(config['bitrate'])
 
-    can.log.debug("loaded can config: {}".format(config))
+    can.log.debug("can config: {}".format(config))
     return config
 
-
+            
 def set_logging_level(level_name=None):
     """Set the logging level for the "can" logger.
     Expects one of: 'critical', 'error', 'warning', 'info', 'debug', 'subdebug'

doc/bcm.rst

@@ -1,57 +1,51 @@
 Broadcast Manager
 =================
 
+.. module:: can.broadcastmanager
+
 The broadcast manager isn't yet supported by all interfaces.
-Currently SockerCAN and IXXAT are supported at least partially.
+Currently SocketCAN and IXXAT are supported at least partially.
 It allows the user to setup periodic message jobs.
 
 If periodic transmission is not supported natively, a software thread
 based scheduler is used as a fallback.
 
-This example shows the socketcan_ctypes backend using the broadcast manager:
-
+This example shows the socketcan backend using the broadcast manager:
 
 .. literalinclude:: ../examples/cyclic.py
     :language: python
     :linenos:
 
 
-Class based API
----------------
-
-.. autoclass:: can.broadcastmanager.CyclicTask
-    :members:
+Message Sending Tasks
+~~~~~~~~~~~~~~~~~~~~~
 
+The class based api for the broadcast manager uses a series of
+`mixin classes <https://www.ianlewis.org/en/mixins-and-python>`_.
+All mixins inherit from :class:`~can.broadcastmanager.CyclicSendTaskABC`
 
 .. autoclass:: can.broadcastmanager.CyclicSendTaskABC
     :members:
 
-.. autoclass:: can.broadcastmanager.LimitedDurationCyclicSendTaskABC
+.. autoclass:: LimitedDurationCyclicSendTaskABC
     :members:
 
-
-.. autoclass:: can.broadcastmanager.RestartableCyclicTaskABC
+.. autoclass:: MultiRateCyclicSendTaskABC
     :members:
 
-
-.. autoclass:: can.broadcastmanager.ModifiableCyclicTaskABC
+.. autoclass:: can.ModifiableCyclicTaskABC
     :members:
 
-.. autoclass:: can.broadcastmanager.MultiRateCyclicSendTaskABC
+.. autoclass:: can.RestartableCyclicTaskABC
     :members:
 
-.. autoclass:: can.broadcastmanager.ThreadBasedCyclicSendTask
-    :members:
-
-
 
 Functional API
 --------------
 
-.. note::
-    The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated.
+.. warning::
+    The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated
+    and will be removed in version 2.3.
     Use the object oriented API via :meth:`can.BusABC.send_periodic` instead.
 
-
 .. autofunction:: can.broadcastmanager.send_periodic
-

doc/bus.rst

@@ -3,8 +3,8 @@
 Bus
 ---
 
-The :class:`can.BusABC` class, as the name suggests, provides an abstraction of a CAN bus.
-The bus provides an abstract wrapper around a physical or virtual CAN Bus.
+The :class:`~can.BusABC` class, as the name suggests, provides an abstraction of a CAN bus.
+The bus provides a wrapper around a physical or virtual CAN Bus.
 
 A thread safe bus wrapper is also available, see `Thread safe bus`_.
 
@@ -61,10 +61,10 @@ It can be used exactly like the normal :class:`~can.BusABC`:
 .. autoclass:: can.ThreadSafeBus
     :members:
 
+
 Autoconfig Bus
 --------------
 
 .. autoclass:: can.interface.Bus
     :members:
     :special-members: __iter__
-

doc/conf.py

@@ -28,6 +28,8 @@
 
 # -- General configuration -----------------------------------------------------
 
+primary_domain = 'py'
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
@@ -45,7 +47,7 @@
 }
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None)
+    'python': ('https://docs.python.org/3/', None),
 }
 
 # If this is True, todo and todolist produce output, else they produce nothing.

doc/development.rst

@@ -42,8 +42,9 @@ These steps are a guideline on how to add a new backend to python-can.
   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

doc/interfaces/serial.rst

@@ -8,8 +8,8 @@ The interface is a simple implementation that has been used for
 recording CAN traces.
 
 .. note::
-    The properties extended_id, is_remote_frame and is_error_frame
-    from the class can.Message are not in use. These interface will not
+    The properties **extended_id**, **is_remote_frame** and **is_error_frame**
+    from the class:`~can.Message` are not in use. This interface will not
     send or receive flags for this properties.
 
 Bus
@@ -95,4 +95,4 @@ Examples of serial frames
 | Start of frame | Timestamp           | DLC  | Arbitration ID      | End of frame |
 +================+=====================+======+=====================+==============+
 | 0xAA           | 0x66 0x73 0x00 0x00 | 0x00 | 0x01 0x00 0x00 0x00 | 0xBBS        |
-+----------------+---------------------+------+---------------------+--------------+
++----------------+---------------------+------+---------------------+--------------+

doc/listeners.rst

@@ -13,7 +13,7 @@ Listeners are registered with :ref:`notifier` object(s) which ensure they are
 notified whenever a new message is received.
 
 Subclasses of Listener that do not override **on_message_received** will cause
-`NotImplementedError` to be thrown when a message is received on
+:class:`NotImplementedError` to be thrown when a message is received on
 the CAN bus.
 
 .. autoclass:: can.Listener
@@ -31,7 +31,7 @@ Logger
 ------
 
 The :class:`can.Logger` uses the following :class:`can.Listener` types to
-create *.asc*, *.csv* and *.db* files with the messages received.
+create log files with different file types of the messages received.
 
 .. autoclass:: can.Logger
     :members:
@@ -50,13 +50,20 @@ CSVWriter
 .. autoclass:: can.CSVWriter
     :members:
 
+.. autoclass:: can.CSVReader
+    :members:
+
 
 SqliteWriter
 ------------
 
 .. autoclass:: can.SqliteWriter
     :members:
 
+.. autoclass:: can.SqliteReader
+    :members:
+
+
 Database table format
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -113,12 +120,12 @@ As specification following references can-utils can be used:
 `log2asc <https://github.com/linux-can/can-utils/blob/master/log2asc.c>`_.
 
 
-.. autoclass:: can.io.CanutilsLogWriter
+.. autoclass:: can.CanutilsLogWriter
     :members:
 
-CanutilsLogReader reads CAN data from ASCII log files .log
+**CanutilsLogReader** reads CAN data from ASCII log files .log
 
-.. autoclass:: can.io.CanutilsLogReader
+.. autoclass:: can.CanutilsLogReader
     :members:
 
 
@@ -130,12 +137,12 @@ CAN log format from Vector Informatik GmbH.
 
 The data is stored in a compressed format which makes it very compact.
 
-.. note::
-
-    Channels will be converted to integers.
+.. note:: Channels will be converted to integers.
 
 .. autoclass:: can.BLFWriter
     :members:
 
+The following class can be used to read messages from BLF file:
+
 .. autoclass:: can.BLFReader
     :members: