Feature travis to build sphinx docs (#342)

* Get travis CI to build the sphinx docs
* Various documentation updates (primarily to minimize sphinx warnings)
* Pypy is having issues with building sphinx docs so just build for python 3.6
* Enabled nitpick mode, but not turn warnings into errors

Closes #340

Author: hardbyte

.travis.yml

@@ -7,7 +7,7 @@ python:
   - "3.4"
   - "3.5"
   - "3.6"
-  - "3.7-dev" # TODO: change to "3.7" once it gets released
+  - "3.7-dev" # TODO: change to "3.7" once it is supported by travis-ci
   - "nightly"
   # PyPy:
   - "pypy"
@@ -46,6 +46,11 @@ matrix:
 install:
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo bash test/open_vcan.sh ; fi
   - travis_retry pip install .[test]
+  - travis_retry pip install sphinx
 
 script:
   - pytest -v --timeout=300
+  # Build Docs with Sphinx
+  #
+  # -a Write all files
+  - if [[ "$TRAVIS_PYTHON_VERSION" == "3.6" ]]; then python -m sphinx -an doc build; fi

can/__init__.py

@@ -15,9 +15,10 @@
 
 rc = dict()
 
+
 class CanError(IOError):
-    """
-    Indicates an error with the CAN network.
+    """Indicates an error with the CAN network.
+
     """
     pass
 

can/broadcastmanager.py

@@ -10,11 +10,10 @@
 
 import abc
 import logging
-import sched
+
 import threading
 import time
 
-import can
 
 log = logging.getLogger('can.bcm')
 
@@ -77,7 +76,7 @@ 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:`Message.data`.
+        :param message: The :class:`~can.Message` with new :attr:`can.Message.data`.
         """
         self.message = message
 
@@ -136,9 +135,12 @@ def _run(self):
 
 
 def send_periodic(bus, message, period, *args, **kwargs):
+    """Send a message every `period` seconds on the given channel.
+
+    :param bus: The :class:`can.BusABC` to transmit to.
+    :param message: The :class:`can.Message` instance to periodically send
+    :return: A started task instance
     """
-    Send a message every `period` seconds on the given channel.
-    """
-    log.warn("The method `can.send_periodic` is deprecated and will "
+    log.warning("The function `can.send_periodic` is deprecated and will " +
              "be removed in version 2.3. Please use `can.Bus.send_periodic` instead.")
     return bus.send_periodic(message, period, *args, **kwargs)

can/bus.py

@@ -159,7 +159,7 @@ def send_periodic(self, msg, period, duration=None):
             no duration is provided, the task will continue indefinitely.
 
         :return: A started task instance
-        :rtype: can.CyclicSendTaskABC
+        :rtype: can.broadcastmanager.CyclicSendTaskABC
 
         .. note::
 
@@ -211,7 +211,7 @@ def set_filters(self, filters=None):
         Calling without passing any filters will reset the applied
         filters to `None`.
 
-        :param Iterator[dict] filters:
+        :param filters:
             A iterable of dictionaries each containing a "can_id", a "can_mask",
             and an optional "extended" key.
 
@@ -221,7 +221,6 @@ def set_filters(self, filters=None):
             If ``extended`` is set as well, it only matches messages where
             ``<received_is_extended> == extended``. Else it matches every messages based
             only on the arbitration ID and mask.
-
         """
         self._filters = filters or None
         self._apply_filters(self._filters)

can/interface.py

@@ -29,6 +29,7 @@
 log = logging.getLogger('can.interface')
 log_autodetect = log.getChild('detect_available_configs')
 
+
 def _get_class_for_interface(interface):
     """
     Returns the main bus class for the given interface.
@@ -66,7 +67,8 @@ def _get_class_for_interface(interface):
 
 
 class Bus(BusABC):
-    """
+    """Bus wrapper with configuration loading.
+
     Instantiates a CAN Bus of the given ``interface``, falls back to reading a
     configuration file from default locations.
     """
@@ -130,9 +132,9 @@ def detect_available_configs(interfaces=None):
         - the name of an interface to be searched in as a string,
         - an iterable of interface names to search in, or
         - `None` to search in all known interfaces.
-    :rtype: list of `dict`s
+    :rtype: list[dict]
     :return: an iterable of dicts, each suitable for usage in
-             :class:`can.interface.Bus`'s constructor.
+             :class:`can.interface.Bus`\ 's constructor.
     """
 
     # Figure out where to search

can/notifier.py

@@ -18,8 +18,8 @@ def __init__(self, bus, listeners, timeout=1):
         """Manages the distribution of **Messages** from a given bus/buses to a
         list of listeners.
 
-        :param can.Bus bus: The :ref:`bus` or a list of buses to listen to.
-        :param list listeners: An iterable of :class:`~can.Listener`s
+        :param can.BusABC bus: The :ref:`bus` or a list of buses to listen to.
+        :param list listeners: An iterable of :class:`~can.Listener`
         :param float timeout: An optional maximum number of seconds to wait for any message.
         """
         self.listeners = listeners

can/thread_safe_bus.py

@@ -1,12 +1,7 @@
 #!/usr/bin/env python
 # coding: utf-8
 
-"""
-"""
-
 from __future__ import print_function, absolute_import
-
-from abc import ABCMeta
 from threading import RLock
 
 try:
@@ -19,7 +14,6 @@
     import_exc = exc
 
 from .interface import Bus
-from .bus import BusABC
 
 
 class NullContextManager(object):

doc/api.rst

@@ -18,7 +18,6 @@ A form of CAN interface is also required.
    bcm
 
 
-
 Utilities
 ---------
 
@@ -27,14 +26,20 @@ Utilities
 
 .. automethod:: can.detect_available_configs
 
-.. _notifier:
 
 
 
+.. _notifier:
+
 Notifier
 --------
 
 The Notifier object is used as a message distributor for a bus.
 
 .. autoclass:: can.Notifier
     :members:
+
+Errors
+------
+
+.. autoclass:: can.CanError

doc/bcm.rst

@@ -16,17 +16,42 @@ This example shows the socketcan_ctypes backend using the broadcast manager:
     :linenos:
 
 
-.. note::
-    The functional APi in :meth:`can.send_periodic` is now deprected.
-    Use the object oriented APi in :meth:`can.BusABC.send_periodic` instead.
-
-
 Class based API
 ---------------
 
-.. autoclass:: can.CyclicSendTaskABC
+.. autoclass:: can.broadcastmanager.CyclicTask
+    :members:
+
+
+.. autoclass:: can.broadcastmanager.CyclicSendTaskABC
+    :members:
+
+.. autoclass:: can.broadcastmanager.LimitedDurationCyclicSendTaskABC
+    :members:
+
+
+.. autoclass:: can.broadcastmanager.RestartableCyclicTaskABC
     :members:
 
 
-.. autoclass:: can.MultiRateCyclicSendTaskABC
+.. autoclass:: can.broadcastmanager.ModifiableCyclicTaskABC
     :members:
+
+.. autoclass:: can.broadcastmanager.MultiRateCyclicSendTaskABC
+    :members:
+
+.. autoclass:: can.broadcastmanager.ThreadBasedCyclicSendTask
+    :members:
+
+
+
+Functional API
+--------------
+
+.. note::
+    The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated.
+    Use the object oriented API via :meth:`can.BusABC.send_periodic` instead.
+
+
+.. autofunction:: can.broadcastmanager.send_periodic
+

doc/bus.rst

@@ -3,36 +3,25 @@
 Bus
 ---
 
-The :class:`~can.Bus` class, as the name suggests, provides an abstraction of a CAN 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.
 
 A thread safe bus wrapper is also available, see `Thread safe bus`_.
 
 
-Filtering
-'''''''''
-
-Message filtering can be set up for each bus. Where the interface supports it, this is carried
-out in the hardware or kernel layer - not in Python.
-
-
 API
 ''''
 
 .. autoclass:: can.BusABC
     :members:
     :special-members: __iter__
 
-.. autoclass:: can.interface.Bus
-    :members:
-    :special-members: __iter__
-
 
 Transmitting
 ''''''''''''
 
-Writing to the bus is done by calling the :meth:`~can.BusABC.send()` method and
-passing a :class:`~can.Message` object.
+Writing to the bus is done by calling the :meth:`~can.BusABC.send` method and
+passing a :class:`~can.Message` instance.
 
 
 Receiving
@@ -48,14 +37,21 @@ Alternatively the :class:`~can.Listener` api can be used, which is a list of :cl
 subclasses that receive notifications when new messages arrive.
 
 
+Filtering
+'''''''''
+
+Message filtering can be set up for each bus. Where the interface supports it, this is carried
+out in the hardware or kernel layer - not in Python.
+
+
 Thread safe bus
 ---------------
 
-This thread safe version of the :class:`~can.Bus` class can be used by multiple threads at once.
-Sending and receiving is locked seperatly to avoid unnessesary delays.
+This thread safe version of the :class:`~can.BusABC` class can be used by multiple threads at once.
+Sending and receiving is locked separately to avoid unnecessary delays.
 Conflicting calls are executed by blocking until the bus is accessible.
 
-It can be used exactly like the normal :class:`~can.Bus`:
+It can be used exactly like the normal :class:`~can.BusABC`:
 
     # 'socketcan' is only an exemple interface, it works with all the others too
     my_bus = can.ThreadSafeBus(interface='socketcan', channel='vcan0')
@@ -64,3 +60,11 @@ It can be used exactly like the normal :class:`~can.Bus`:
 
 .. autoclass:: can.ThreadSafeBus
     :members:
+
+Autoconfig Bus
+--------------
+
+.. autoclass:: can.interface.Bus
+    :members:
+    :special-members: __iter__
+