Skip to content

Commit d3103d8

Browse files
zariiii9003zariiii9003
authored
update docs (hardbyte#1421)
1 parent 4b43f33 commit d3103d8

17 files changed

+170
-85
lines changed

‎can/interface.py

+29-22
Original file line numberDiff line numberDiff line change
@@ -60,37 +60,44 @@ class Bus(BusABC): # pylint: disable=abstract-method
6060
6161
Instantiates a CAN Bus of the given ``interface``, falls back to reading a
6262
configuration file from default locations.
63-
"""
6463
65-
@staticmethod
66-
def __new__( # type: ignore # pylint: disable=keyword-arg-before-vararg
67-
cls: Any, channel: Optional[Channel] = None, *args: Any, **kwargs: Any
68-
) -> BusABC:
69-
"""
70-
Takes the same arguments as :class:`can.BusABC.__init__`.
71-
Some might have a special meaning, see below.
64+
:param channel:
65+
Channel identification. Expected type is backend dependent.
66+
Set to ``None`` to let it be resolved automatically from the default
67+
:ref:`configuration`.
7268
73-
:param channel:
74-
Set to ``None`` to let it be resolved automatically from the default
75-
configuration. That might fail, see below.
69+
:param interface:
70+
See :ref:`interface names` for a list of supported interfaces.
71+
Set to ``None`` to let it be resolved automatically from the default
72+
:ref:`configuration`.
7673
77-
Expected type is backend dependent.
74+
:param args:
75+
``interface`` specific positional arguments.
7876
79-
:param dict kwargs:
80-
Should contain an ``interface`` key with a valid interface name. If not,
81-
it is completed using :meth:`can.util.load_config`.
77+
:param kwargs:
78+
``interface`` specific keyword arguments.
8279
83-
:raises: can.CanInterfaceNotImplementedError
84-
if the ``interface`` isn't recognized or cannot be loaded
80+
:raises ~can.exceptions.CanInterfaceNotImplementedError:
81+
if the ``interface`` isn't recognized or cannot be loaded
8582
86-
:raises: can.CanInitializationError
87-
if the bus cannot be instantiated
83+
:raises ~can.exceptions.CanInitializationError:
84+
if the bus cannot be instantiated
8885
89-
:raises: ValueError
90-
if the ``channel`` could not be determined
91-
"""
86+
:raises ValueError:
87+
if the ``channel`` could not be determined
88+
"""
9289

90+
@staticmethod
91+
def __new__( # type: ignore # pylint: disable=keyword-arg-before-vararg
92+
cls: Any,
93+
channel: Optional[Channel] = None,
94+
interface: Optional[str] = None,
95+
*args: Any,
96+
**kwargs: Any,
97+
) -> BusABC:
9398
# figure out the rest of the configuration; this might raise an error
99+
if interface is not None:
100+
kwargs["interface"] = interface
94101
if channel is not None:
95102
kwargs["channel"] = channel
96103
if "context" in kwargs:

‎can/interfaces/cantact.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ def __init__(
5959
Bitrate in bits/s
6060
:param bool monitor:
6161
If true, operate in listen-only monitoring mode
62-
:param BitTiming bit_timing
62+
:param BitTiming bit_timing:
6363
Optional BitTiming to use for custom bit timing setting. Overrides bitrate if not None.
6464
"""
6565

‎doc/api.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Library API
22
===========
33

4-
The main objects are the :class:`~can.BusABC` and the :class:`~can.Message`.
4+
The main objects are the :class:`~can.Bus` and the :class:`~can.Message`.
55
A form of CAN interface is also required.
66

77
.. hint::

‎doc/bus.rst

+4-17
Original file line numberDiff line numberDiff line change
@@ -15,24 +15,11 @@ and implements the :class:`~can.BusABC` API.
1515

1616
A thread safe bus wrapper is also available, see `Thread safe bus`_.
1717

18-
Autoconfig Bus
19-
''''''''''''''
20-
2118
.. autoclass:: can.Bus
19+
:class-doc-from: class
20+
:show-inheritance:
2221
:members:
23-
24-
25-
API
26-
'''
27-
28-
.. autoclass:: can.BusABC
29-
:members:
30-
31-
.. automethod:: __iter__
32-
.. automethod:: _recv_internal
33-
.. automethod:: _apply_filters
34-
.. automethod:: _detect_available_configs
35-
.. automethod:: _send_periodic_internal
22+
:inherited-members:
3623

3724
.. autoclass:: can.bus.BusState
3825
:members:
@@ -81,7 +68,7 @@ Example defining two filters, one to pass 11-bit ID ``0x451``, the other to pass
8168
See :meth:`~can.BusABC.set_filters` for the implementation.
8269

8370
Thread safe bus
84-
---------------
71+
'''''''''''''''
8572

8673
This thread safe version of the :class:`~can.BusABC` class can be used by multiple threads at once.
8774
Sending and receiving is locked separately to avoid unnecessary delays.

‎doc/conf.py

+1
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
"sphinx.ext.viewcode",
4949
"sphinx.ext.graphviz",
5050
"sphinxcontrib.programoutput",
51+
"sphinx_inline_tabs",
5152
"sphinx_rtd_theme",
5253
]
5354

‎doc/configuration.rst

+34-11
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _configuration:
2+
13
Configuration
24
=============
35

@@ -100,6 +102,7 @@ For example:
100102

101103
``CAN_INTERFACE=socketcan CAN_CONFIG={"receive_own_messages": true, "fd": true}``
102104

105+
.. _interface names:
103106

104107
Interface Names
105108
---------------
@@ -109,31 +112,51 @@ Lookup table of interface names:
109112
+---------------------+-------------------------------------+
110113
| Name | Documentation |
111114
+=====================+=====================================+
112-
| ``"socketcan"`` | :doc:`interfaces/socketcan` |
115+
| ``"canalystii"`` | :doc:`interfaces/canalystii` |
113116
+---------------------+-------------------------------------+
114-
| ``"kvaser"`` | :doc:`interfaces/kvaser` |
117+
| ``"cantact"`` | :doc:`interfaces/cantact` |
115118
+---------------------+-------------------------------------+
116-
| ``"serial"`` | :doc:`interfaces/serial` |
119+
| ``"etas"`` | :doc:`interfaces/etas` |
117120
+---------------------+-------------------------------------+
118-
| ``"slcan"`` | :doc:`interfaces/slcan` |
121+
| ``"gs_usb"`` | :doc:`interfaces/gs_usb` |
122+
+---------------------+-------------------------------------+
123+
| ``"iscan"`` | :doc:`interfaces/iscan` |
119124
+---------------------+-------------------------------------+
120125
| ``"ixxat"`` | :doc:`interfaces/ixxat` |
121126
+---------------------+-------------------------------------+
122-
| ``"pcan"`` | :doc:`interfaces/pcan` |
127+
| ``"kvaser"`` | :doc:`interfaces/kvaser` |
123128
+---------------------+-------------------------------------+
124-
| ``"usb2can"`` | :doc:`interfaces/usb2can` |
129+
| ``"neousys"`` | :doc:`interfaces/neousys` |
130+
+---------------------+-------------------------------------+
131+
| ``"neovi"`` | :doc:`interfaces/neovi` |
125132
+---------------------+-------------------------------------+
126133
| ``"nican"`` | :doc:`interfaces/nican` |
127134
+---------------------+-------------------------------------+
128-
| ``"iscan"`` | :doc:`interfaces/iscan` |
135+
| ``"nixnet"`` | :doc:`interfaces/nixnet` |
129136
+---------------------+-------------------------------------+
130-
| ``"neovi"`` | :doc:`interfaces/neovi` |
137+
| ``"pcan"`` | :doc:`interfaces/pcan` |
131138
+---------------------+-------------------------------------+
132-
| ``"vector"`` | :doc:`interfaces/vector` |
139+
| ``"robotell"`` | :doc:`interfaces/robotell` |
133140
+---------------------+-------------------------------------+
134-
| ``"virtual"`` | :doc:`interfaces/virtual` |
141+
| ``"seeedstudio"`` | :doc:`interfaces/seeedstudio` |
135142
+---------------------+-------------------------------------+
136-
| ``"canalystii"`` | :doc:`interfaces/canalystii` |
143+
| ``"serial"`` | :doc:`interfaces/serial` |
144+
+---------------------+-------------------------------------+
145+
| ``"slcan"`` | :doc:`interfaces/slcan` |
146+
+---------------------+-------------------------------------+
147+
| ``"socketcan"`` | :doc:`interfaces/socketcan` |
148+
+---------------------+-------------------------------------+
149+
| ``"socketcand"`` | :doc:`interfaces/socketcand` |
137150
+---------------------+-------------------------------------+
138151
| ``"systec"`` | :doc:`interfaces/systec` |
139152
+---------------------+-------------------------------------+
153+
| ``"udp_multicast"`` | :doc:`interfaces/udp_multicast` |
154+
+---------------------+-------------------------------------+
155+
| ``"usb2can"`` | :doc:`interfaces/usb2can` |
156+
+---------------------+-------------------------------------+
157+
| ``"vector"`` | :doc:`interfaces/vector` |
158+
+---------------------+-------------------------------------+
159+
| ``"virtual"`` | :doc:`interfaces/virtual` |
160+
+---------------------+-------------------------------------+
161+
162+
Additional interface types can be added via the :ref:`plugin interface`.

‎doc/development.rst

+8-4
Original file line numberDiff line numberDiff line change
@@ -35,17 +35,16 @@ The following assumes that the commands are executed from the root of the reposi
3535

3636
The project can be built with::
3737

38-
pip install wheel
39-
python setup.py sdist bdist_wheel
38+
pipx run build
39+
pipx run twine check dist/*
4040

4141
The project can be installed in editable mode with::
4242

4343
pip install -e .
4444

4545
The unit tests can be run with::
4646

47-
pip install tox
48-
tox -e py
47+
pipx run tox -e py
4948

5049
The documentation can be built with::
5150

@@ -79,6 +78,11 @@ These steps are a guideline on how to add a new backend to python-can.
7978
To get started, have a look at ``back2back_test.py``:
8079
Simply add a test case like ``BasicTestSocketCan`` and some basic tests will be executed for the new interface.
8180

81+
.. attention::
82+
We strongly recommend using the :ref:`plugin interface` to extend python-can.
83+
Publish a python package that contains your :class:`can.BusABC` subclass and use
84+
it within the python-can API. We will mention your package inside this documentation
85+
and add it as an optional dependency.
8286

8387
Code Structure
8488
--------------

‎doc/doc-requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
sphinx>=5.2.3
22
sphinxcontrib-programoutput
33
sphinx_rtd_theme
4+
sphinx-inline-tabs

‎doc/interfaces.rst

+54-11
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _can interface modules:
2+
13
CAN Interface Modules
24
---------------------
35

@@ -12,11 +14,13 @@ The available interfaces are:
1214
:maxdepth: 1
1315

1416
interfaces/canalystii
17+
interfaces/cantact
1518
interfaces/etas
1619
interfaces/gs_usb
1720
interfaces/iscan
1821
interfaces/ixxat
1922
interfaces/kvaser
23+
interfaces/neousys
2024
interfaces/neovi
2125
interfaces/nican
2226
interfaces/nixnet
@@ -33,19 +37,58 @@ The available interfaces are:
3337
interfaces/vector
3438
interfaces/virtual
3539

36-
Additional interfaces can be added via a plugin interface. An external package
37-
can register a new interface by using the ``can.interface`` entry point in its setup.py.
40+
The *Interface Names* are listed in :doc:`configuration`.
3841

39-
The format of the entry point is ``interface_name=module:classname`` where
40-
``classname`` is a concrete :class:`can.BusABC` implementation.
4142

42-
::
43+
.. _plugin interface:
4344

44-
entry_points={
45-
'can.interface': [
46-
"interface_name=module:classname",
47-
]
48-
},
45+
Plugin Interface
46+
^^^^^^^^^^^^^^^^
4947

48+
External packages can register a new interfaces by using the ``can.interface`` entry point
49+
in its project configuration. The format of the entry point depends on your project
50+
configuration format (*pyproject.toml*, *setup.cfg* or *setup.py*).
5051

51-
The *Interface Names* are listed in :doc:`configuration`.
52+
In the following example ``module`` defines the location of your bus class inside your
53+
package e.g. ``my_package.subpackage.bus_module`` and ``classname`` is the name of
54+
your :class:`can.BusABC` subclass.
55+
56+
.. tab:: pyproject.toml (PEP 621)
57+
58+
.. code-block:: toml
59+
60+
# Note the quotes around can.interface in order to escape the dot .
61+
[project.entry-points."can.interface"]
62+
interface_name = "module:classname"
63+
64+
.. tab:: setup.cfg
65+
66+
.. code-block:: ini
67+
68+
[options.entry_points]
69+
can.interface =
70+
interface_name = module:classname
71+
72+
.. tab:: setup.py
73+
74+
.. code-block:: python
75+
76+
from setuptools import setup
77+
78+
setup(
79+
# ...,
80+
entry_points = {
81+
'can.interface': [
82+
'interface_name = module:classname'
83+
]
84+
}
85+
)
86+
87+
The ``interface_name`` can be used to
88+
create an instance of the bus in the **python-can** API:
89+
90+
.. code-block:: python
91+
92+
import can
93+
94+
bus = can.Bus(interface="interface_name", channel=0)

‎doc/interfaces/cantact.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
CANtact CAN Interface
2+
=====================
3+
4+
Interface for CANtact devices from Linklayer Labs
5+
6+
.. autoclass:: can.interfaces.cantact.CantactBus
7+
:show-inheritance:
8+
:members:

‎doc/interfaces/neousys.rst

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Neousys CAN Interface
2+
=====================
3+
4+
This kind of interface can be found for example on Neousys POC-551VTC
5+
One needs to have correct drivers and DLL (Share object for Linux) from
6+
`Neousys <https://www.neousys-tech.com/en/support-service/resources/category/299-poc-551vtc-driver>`_.
7+
8+
Beware this is only tested on Linux kernel higher than v5.3. This should be drop in
9+
with Windows but you have to replace with correct named DLL
10+
11+
.. autoclass:: can.interfaces.neousys.NeousysBus
12+
:show-inheritance:
13+
:members:

‎doc/internal-api.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -55,15 +55,15 @@ configuration into account.
5555
Bus Internals
5656
~~~~~~~~~~~~~
5757

58-
Several methods are not documented in the main :class:`can.BusABC`
58+
Several methods are not documented in the main :class:`can.Bus`
5959
as they are primarily useful for library developers as opposed to
6060
library users. This is the entire ABC bus class with all internal
6161
methods:
6262

6363
.. autoclass:: can.BusABC
64+
:members:
6465
:private-members:
6566
:special-members:
66-
:noindex:
6767

6868

6969

0 commit comments

Comments
 (0)