From 57fa6b9a192ec777214bc86d02e637517ea75f07 Mon Sep 17 00:00:00 2001 From: Brian Thorne Date: Mon, 24 Sep 2018 15:42:49 +1000 Subject: [PATCH 1/4] Extract the command line output automatically from scripts --- doc/conf.py | 4 ++- doc/doc-requirements.txt | 2 ++ doc/scripts.rst | 76 +++------------------------------------- 3 files changed, 10 insertions(+), 72 deletions(-) create mode 100644 doc/doc-requirements.txt diff --git a/doc/conf.py b/doc/conf.py index e61801a6f..1c409a06a 100755 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,7 +39,9 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', - 'sphinx.ext.graphviz'] + 'sphinx.ext.graphviz', + 'sphinxcontrib.programoutput' + ] # Now, you can use the alias name as a new role, e.g. :issue:`123`. extlinks = { diff --git a/doc/doc-requirements.txt b/doc/doc-requirements.txt new file mode 100644 index 000000000..45026701b --- /dev/null +++ b/doc/doc-requirements.txt @@ -0,0 +1,2 @@ +sphinx>=1.8.1 +sphinxcontrib-programoutput diff --git a/doc/scripts.rst b/doc/scripts.rst index e10ea87e0..df097f4ce 100644 --- a/doc/scripts.rst +++ b/doc/scripts.rst @@ -8,89 +8,23 @@ They can be called for example by ``python -m can.logger`` or ``can_logger.py`` can.logger ---------- -Command line help, called with ``--help``:: - - usage: python -m can.logger [-h] [-f LOG_FILE] [-v] [-c CHANNEL] - [-i {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native}] - [--filter ...] [-b BITRATE] - [--active | --passive] - - Log CAN traffic, printing messages to stdout or to a given file. - - optional arguments: - -h, --help show this help message and exit - -f LOG_FILE, --file_name LOG_FILE - Path and base log filename, for supported types see - can.Logger. - -v How much information do you want to see at the command - line? You can add several of these e.g., -vv is DEBUG - -c CHANNEL, --channel CHANNEL - Most backend interfaces require some sort of channel. - For example with the serial interface the channel - might be a rfcomm device: "/dev/rfcomm0" With the - socketcan interfaces valid channel examples include: - "can0", "vcan0" - -i {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native}, --interface {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native} - Specify the backend CAN interface to use. If left - blank, fall back to reading from configuration files. - --filter ... Comma separated filters can be specified for the given - CAN interface: : (matches when - & mask == can_id & mask) - ~ (matches when & - mask != can_id & mask) - -b BITRATE, --bitrate BITRATE - Bitrate to use for the CAN bus. - --active Start the bus as active, this is applied the default. - --passive Start the bus as passive. +Command line help, called with ``--help``: -can.player ----------- - -Command line help, called with ``--help``:: +.. command-output:: python -m can.logger -h - usage: python -m can.player [-h] [-f LOG_FILE] [-v] [-c CHANNEL] - [-i {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native}] - [-b BITRATE] [--ignore-timestamps] - [-g GAP] [-s SKIP] - input-file - Replay CAN traffic. +can.player +---------- - positional arguments: - input-file The file to replay. For supported types see - can.LogReader. +.. command-output:: python -m can.player -h - optional arguments: - -h, --help show this help message and exit - -f LOG_FILE, --file_name LOG_FILE - Path and base log filename, for supported types see - can.LogReader. - -v Also print can frames to stdout. You can add several - of these to enable debugging - -c CHANNEL, --channel CHANNEL - Most backend interfaces require some sort of channel. - For example with the serial interface the channel - might be a rfcomm device: "/dev/rfcomm0" With the - socketcan interfaces valid channel examples include: - "can0", "vcan0" - -i {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native}, --interface {pcan,ixxat,socketcan_ctypes,kvaser,virtual,usb2can,vector,slcan,nican,socketcan,iscan,neovi,serial,socketcan_native} - Specify the backend CAN interface to use. If left - blank, fall back to reading from configuration files. - -b BITRATE, --bitrate BITRATE - Bitrate to use for the CAN bus. - --ignore-timestamps Ignore timestamps (send all frames immediately with - minimum gap between frames) - -g GAP, --gap GAP minimum time between replayed frames - -s SKIP, --skip SKIP skip gaps greater than 's' seconds can.viewer ---------- A screenshot of the application can be seen below: -.. image:: ../images/viewer.png - :width: 100% The first column is the number of times a frame with the particular ID that has been received, next is the timestamp of the frame relative to the first received message. The third column is the time between the current frame relative to the previous one. Next is the length of the frame, the data and then the decoded data converted according to the ``-d`` argument. The top red row indicates an error frame. From bfb20dcd82bd7a0e7f4c02be8c503e152c8f8738 Mon Sep 17 00:00:00 2001 From: Brian Thorne Date: Mon, 24 Sep 2018 15:43:07 +1000 Subject: [PATCH 2/4] Minor doc tweaks --- doc/bus.rst | 2 +- doc/development.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/bus.rst b/doc/bus.rst index a73885c68..0b8814c8f 100644 --- a/doc/bus.rst +++ b/doc/bus.rst @@ -68,7 +68,7 @@ Conflicting calls are executed by blocking until the bus is accessible. It can be used exactly like the normal :class:`~can.BusABC`: - # 'socketcan' is only an exemple interface, it works with all the others too + # 'socketcan' is only an example interface, it works with all the others too my_bus = can.ThreadSafeBus(interface='socketcan', channel='vcan0') my_bus.send(...) my_bus.recv(...) diff --git a/doc/development.rst b/doc/development.rst index 51924be16..8a7a17f15 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -86,6 +86,8 @@ 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`. From c660779302bbdac3d95082474744836e3c0a2e2d Mon Sep 17 00:00:00 2001 From: Brian Thorne Date: Mon, 24 Sep 2018 15:57:51 +1000 Subject: [PATCH 3/4] travis needs to install doc deps before calling sphinx --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 164953450..5f8204b29 100644 --- a/.travis.yml +++ b/.travis.yml @@ -50,7 +50,7 @@ matrix: install: - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo bash test/open_vcan.sh ; fi - - travis_retry pip install sphinx + - if [[ "$TRAVIS_PYTHON_VERSION" == "3.6" ]]; then travis_retry pip install -r doc/doc-requirements.txt; fi - travis_retry pip install .[test] script: From ce5ac4b3042a51de5ab997092f93502167b65d5e Mon Sep 17 00:00:00 2001 From: Brian Thorne Date: Tue, 25 Sep 2018 20:23:40 +1000 Subject: [PATCH 4/4] Extract viewer command line help --- doc/scripts.rst | 85 +++++-------------------------------------------- 1 file changed, 8 insertions(+), 77 deletions(-) diff --git a/doc/scripts.rst b/doc/scripts.rst index df097f4ce..2b2290ad1 100644 --- a/doc/scripts.rst +++ b/doc/scripts.rst @@ -25,86 +25,17 @@ can.viewer A screenshot of the application can be seen below: +.. image:: ../images/viewer.png + :width: 100% The first column is the number of times a frame with the particular ID that has been received, next is the timestamp of the frame relative to the first received message. The third column is the time between the current frame relative to the previous one. Next is the length of the frame, the data and then the decoded data converted according to the ``-d`` argument. The top red row indicates an error frame. Command line arguments ^^^^^^^^^^^^^^^^^^^^^^ -By default it will be using the :doc:`/interfaces/socketcan` interface. All interfaces supported are supported and can be specified using the ``-i`` argument. - -The full usage page can be seen below:: - - Usage: python -m can.viewer [-h] [--version] [-b BITRATE] [-c CHANNEL] - [-d {:,:::...:,file.txt}] - [-f {:,~}] - [-i {iscan,ixxat,kvaser,neovi,nican,pcan,serial,slcan,socketcan,socketcan_ctypes,socketcan_native,usb2can,vector,virtual}] - - A simple CAN viewer terminal application written in Python - - Optional arguments: - -h, --help Show this help message and exit - --version Show program's version number and exit - -b, --bitrate BITRATE - Bitrate to use for the given CAN interface - -c, --channel CHANNEL - Most backend interfaces require some sort of channel. - For example with the serial interface the channel - might be a rfcomm device: "/dev/rfcomm0" with the - socketcan interfaces valid channel examples include: - "can0", "vcan0". (default: use default for the - specified interface) - -d, --decode {:,:::...:,file.txt} - Specify how to convert the raw bytes into real values. - The ID of the frame is given as the first argument and the format as the second. - The Python struct package is used to unpack the received data - where the format characters have the following meaning: - < = little-endian, > = big-endian - x = pad byte - c = char - ? = bool - b = int8_t, B = uint8_t - h = int16, H = uint16 - l = int32_t, L = uint32_t - q = int64_t, Q = uint64_t - f = float (32-bits), d = double (64-bits) - Fx to convert six bytes with ID 0x100 into uint8_t, uint16 and uint32_t: - $ python -m can.viewer -d "100::,~} - Comma separated CAN filters for the given CAN interface: - : (matches when & mask == can_id & mask) - ~ (matches when & mask != can_id & mask) - Fx to show only frames with ID 0x100 to 0x103: - python -m can.viewer -f 100:7FC - Note that the ID and mask are alway interpreted as hex values - -i, --interface {iscan,ixxat,kvaser,neovi,nican,pcan,serial,slcan,socketcan,socketcan_ctypes,socketcan_native,usb2can,vector,virtual} - Specify the backend CAN interface to use. - - Shortcuts: - +---------+-------------------------+ - | Key | Description | - +---------+-------------------------+ - | ESQ/q | Exit the viewer | - | c | Clear the stored frames | - | s | Sort the stored frames | - | SPACE | Pause the viewer | - | UP/DOWN | Scroll the viewer | - +---------+-------------------------+ +By default the ``can.viewer`` uses the :doc:`/interfaces/socketcan` interface. All interfaces are supported and can be specified using the ``-i`` argument or configured following :doc:`/configuration`. + +The full usage page can be seen below: + +.. command-output:: python -m can.viewer -h +