Documentation update (#486)

* Add try except around importing curses to support windows
* Update docstrings for MultiRateCyclicSendTask
* Move some internal stuff into own internal api page.
* More doc updates - trying to reduce sphinx warnings

Author: hardbyte

can/broadcastmanager.py

@@ -85,15 +85,15 @@ def modify_data(self, message):
 
 
 class MultiRateCyclicSendTaskABC(CyclicSendTaskABC):
-    """Exposes more of the full power of the TX_SETUP opcode.
+    """A Cyclic send task that supports switches send frequency after a set time.
     """
 
     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 channel: See interface specific documentation.
         :param can.Message message:
         :param int count:
         :param float initial_period:

can/bus.py

@@ -167,8 +167,8 @@ def send_periodic(self, msg, period, duration=None, store_task=True):
         - the (optional) duration expires
         - the Bus instance goes out of scope
         - the Bus instance is shutdown
-        - :meth:`Bus.stop_all_periodic_tasks()` is called
-        - the task's :meth:`Task.stop()` method is called.
+        - :meth:`BusABC.stop_all_periodic_tasks()` is called
+        - the task's :meth:`CyclicTask.stop()` method is called.
 
         :param can.Message msg:
             Message to transmit

can/interface.py

@@ -1,8 +1,8 @@
 # coding: utf-8
 
 """
-This module contains the base implementation of `can.Bus` as well
-as a list of all avalibale backends and some implemented
+This module contains the base implementation of :class:`can.BusABC` as well
+as a list of all available backends and some implemented
 CyclicSendTasks.
 """
 
@@ -11,7 +11,6 @@
 import sys
 import importlib
 import logging
-import re
 
 import can
 from .bus import BusABC
@@ -145,7 +144,7 @@ def detect_available_configs(interfaces=None):
         - `None` to search in all known interfaces.
     :rtype: list[dict]
     :return: an iterable of dicts, each suitable for usage in
-             the constructor of :class:`can.interface.Bus`.
+             the constructor of :class:`can.BusABC`.
     """
 
     # Figure out where to search

can/interfaces/socketcan/socketcan.py

@@ -303,8 +303,7 @@ def start(self):
 class MultiRateCyclicSendTask(CyclicSendTask):
     """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):

can/io/generic.py

@@ -26,7 +26,7 @@ def __init__(self, file, mode='rt'):
         :param file: a path-like object to open a file, a file-like object
                      to be used as a file or `None` to not use a file at all
         :param str mode: the mode that should be used to open the file, see
-                         :func:`builtin.open`, ignored if *file* is `None`
+                         :func:`open`, ignored if *file* is `None`
         """
         if file is None or (hasattr(file, 'read') and hasattr(file, 'write')):
             # file is None or some file-like object

can/viewer.py

@@ -25,18 +25,26 @@
 from __future__ import absolute_import, print_function
 
 import argparse
-import can
-import curses
 import os
 import struct
 import sys
 import time
-
-from curses.ascii import ESC as KEY_ESC, SP as KEY_SPACE
+import logging
 from typing import Dict, List, Tuple, Union
-
+import can
 from can import __version__
 
+logger = logging.getLogger('can.serial')
+
+try:
+    import curses
+    from curses.ascii import ESC as KEY_ESC, SP as KEY_SPACE
+except ImportError:
+    # Probably on windows
+    logger.warning("You won't be able to use the viewer program without "
+                   "curses installed!")
+    curses = None
+
 
 class CanViewer:
 

doc/api.rst

@@ -17,19 +17,16 @@ A form of CAN interface is also required.
    listeners
    asyncio
    bcm
+   internal-api
 
 
 Utilities
 ---------
 
-.. automodule:: can.util
-    :members:
 
 .. automethod:: can.detect_available_configs
 
 
-
-
 .. _notifier:
 
 Notifier

doc/bus.rst

@@ -30,6 +30,7 @@ API
     :members:
     :undoc-members:
 
+    .. automethod:: __iter__
 
 Transmitting
 ''''''''''''

doc/development.rst

@@ -35,7 +35,7 @@ These steps are a guideline on how to add a new backend to python-can.
 - Create a module (either a ``*.py`` or an entire subdirectory 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!
+  :class:`can.BusABC`. See :ref:`businternals` for more info on this one!
 - Register your backend bus class in ``can.interface.BACKENDS`` and
   ``can.interfaces.VALID_INTERFACES`` in ``can.interfaces.__init__.py``.
 - Add docs where appropriate. At a minimum add to ``doc/interfaces.rst`` and add
@@ -44,53 +44,6 @@ These steps are a guideline on how to add a new backend to python-can.
 - Add tests in ``test/*`` where appropriate.
 
 
-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 discarding any
-      messages yet to be sent
-    * :meth:`~can.BusABC.shutdown` to override how the bus should
-      shut down
-    * :meth:`~can.BusABC._send_periodic_internal` 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::
-
-    *TL;DR*: Only override :meth:`~can.BusABC._recv_internal`,
-    never :meth:`~can.BusABC.recv` directly.
-    
-    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. All internal interfaces now implement that new
-    behaviour. Older (custom) interfaces might still be implemented like that
-    and thus might not provide message filtering:
-
-This is the entire ABC bus class with all internal methods:
-
-.. autoclass:: can.BusABC
-    :private-members:
-    :special-members:
-    :noindex:
-
-
-Concrete instances are created by :class:`can.Bus`.
-
 
 Code Structure
 --------------

doc/history.rst

@@ -46,8 +46,6 @@ The CAN viewer terminal script was contributed by Kristian Sloth Lauszus in 2018
 
 The CANalyst-II interface was contributed by Shaoyu Meng in 2018.
 
-The SYSTEC interface was contributed by @idaniel86
-
 Support for CAN within Python
 -----------------------------
 

doc/interfaces/canalystii.rst

@@ -1,7 +1,8 @@
 CANalyst-II
 ===========
 
-CANalyst-II(+) is a USB to CAN Analyzer. The controlcan library is originally developed by `ZLG ZHIYUAN Electronics`_.
+CANalyst-II(+) is a USB to CAN Analyzer. The controlcan library is originally developed by
+`ZLG ZHIYUAN Electronics`_.
 
 
 Bus

doc/internal-api.rst

@@ -0,0 +1,84 @@
+Internal API
+============
+
+Here we document the odds and ends that are more helpful for creating your own interfaces
+or listeners but generally shouldn't be required to interact with python-can.
+
+
+.. _businternals:
+
+
+Extending the ``BusABC`` class
+------------------------------
+
+Concrete implementations **must** 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 discarding any
+      messages yet to be sent
+    * :meth:`~can.BusABC.shutdown` to override how the bus should
+      shut down
+    * :meth:`~can.BusABC._send_periodic_internal` 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::
+
+    *TL;DR*: Only override :meth:`~can.BusABC._recv_internal`,
+    never :meth:`~can.BusABC.recv` directly.
+
+    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. All internal interfaces now implement that new
+    behaviour. Older (custom) interfaces might still be implemented like that
+    and thus might not provide message filtering:
+
+
+
+Concrete instances are usually created by :class:`can.Bus` which takes the users
+configuration into account.
+
+
+Bus Internals
+~~~~~~~~~~~~~
+
+Several methods are not documented in the main :class:`can.BusABC`
+as they are primarily useful for library developers as opposed to
+library users. This is the entire ABC bus class with all internal
+methods:
+
+.. autoclass:: can.BusABC
+    :private-members:
+    :special-members:
+    :noindex:
+
+
+
+IO Utilities
+------------
+
+
+.. automodule:: can.io.generic
+    :members:
+
+
+
+Other Util
+----------
+
+
+.. automodule:: can.util
+    :members:
+

doc/message.rst

@@ -113,7 +113,7 @@ Message
 
         .. note::
 
-            The :meth:`Message.__init__` argument ``extended_id`` has been deprecated in favor of
+            The initializer argument and attribute ``extended_id`` has been deprecated in favor of
             ``is_extended_id``, but will continue to work for the ``3.x`` release series.
 
 
@@ -129,7 +129,7 @@ Message
 
     .. attribute:: is_remote_frame
 
-        :type: boolean
+        :type: bool
 
         This boolean attribute indicates if the message is a remote frame or a data frame, and
         modifies the bit in the CAN message's flags field indicating this.