Revert "update docs (hardbyte#1421)"

This reverts commit d3103d8.

Author: j-c-cook

can/interface.py

@@ -60,44 +60,37 @@ class Bus(BusABC):  # pylint: disable=abstract-method
 
     Instantiates a CAN Bus of the given ``interface``, falls back to reading a
     configuration file from default locations.
+    """
 
-    :param channel:
-        Channel identification. Expected type is backend dependent.
-        Set to ``None`` to let it be resolved automatically from the default
-        :ref:`configuration`.
+    @staticmethod
+    def __new__(  # type: ignore  # pylint: disable=keyword-arg-before-vararg
+        cls: Any, channel: Optional[Channel] = None, *args: Any, **kwargs: Any
+    ) -> BusABC:
+        """
+        Takes the same arguments as :class:`can.BusABC.__init__`.
+        Some might have a special meaning, see below.
 
-    :param interface:
-        See :ref:`interface names` for a list of supported interfaces.
-        Set to ``None`` to let it be resolved automatically from the default
-        :ref:`configuration`.
+        :param channel:
+            Set to ``None`` to let it be resolved automatically from the default
+            configuration. That might fail, see below.
 
-    :param args:
-        ``interface`` specific positional arguments.
+            Expected type is backend dependent.
 
-    :param kwargs:
-        ``interface`` specific keyword arguments.
+        :param dict kwargs:
+            Should contain an ``interface`` key with a valid interface name. If not,
+            it is completed using :meth:`can.util.load_config`.
 
-    :raises ~can.exceptions.CanInterfaceNotImplementedError:
-        if the ``interface`` isn't recognized or cannot be loaded
+        :raises: can.CanInterfaceNotImplementedError
+            if the ``interface`` isn't recognized or cannot be loaded
 
-    :raises ~can.exceptions.CanInitializationError:
-        if the bus cannot be instantiated
+        :raises: can.CanInitializationError
+            if the bus cannot be instantiated
 
-    :raises ValueError:
-        if the ``channel`` could not be determined
-    """
+        :raises: ValueError
+            if the ``channel`` could not be determined
+        """
 
-    @staticmethod
-    def __new__(  # type: ignore  # pylint: disable=keyword-arg-before-vararg
-        cls: Any,
-        channel: Optional[Channel] = None,
-        interface: Optional[str] = None,
-        *args: Any,
-        **kwargs: Any,
-    ) -> BusABC:
         # figure out the rest of the configuration; this might raise an error
-        if interface is not None:
-            kwargs["interface"] = interface
         if channel is not None:
             kwargs["channel"] = channel
         if "context" in kwargs:

can/interfaces/cantact.py

@@ -59,7 +59,7 @@ def __init__(
             Bitrate in bits/s
         :param bool monitor:
             If true, operate in listen-only monitoring mode
-        :param BitTiming bit_timing:
+        :param BitTiming bit_timing
             Optional BitTiming to use for custom bit timing setting. Overrides bitrate if not None.
         """
 

doc/api.rst

@@ -1,7 +1,7 @@
 Library API
 ===========
 
-The main objects are the :class:`~can.Bus` and the :class:`~can.Message`.
+The main objects are the :class:`~can.BusABC` and the :class:`~can.Message`.
 A form of CAN interface is also required.
 
 .. hint::

doc/bus.rst

@@ -15,11 +15,24 @@ and implements the :class:`~can.BusABC` API.
 
 A thread safe bus wrapper is also available, see `Thread safe bus`_.
 
+Autoconfig Bus
+''''''''''''''
+
 .. autoclass:: can.Bus
-    :class-doc-from: class
-    :show-inheritance:
     :members:
-    :inherited-members:
+
+
+API
+'''
+
+.. autoclass:: can.BusABC
+    :members:
+
+    .. automethod:: __iter__
+    .. automethod:: _recv_internal
+    .. automethod:: _apply_filters
+    .. automethod:: _detect_available_configs
+    .. automethod:: _send_periodic_internal
 
 .. autoclass:: can.bus.BusState
     :members:
@@ -68,7 +81,7 @@ Example defining two filters, one to pass 11-bit ID ``0x451``, the other to pass
 See :meth:`~can.BusABC.set_filters` for the implementation.
 
 Thread safe bus
-'''''''''''''''
+---------------
 
 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.

doc/conf.py

@@ -48,7 +48,6 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.graphviz",
     "sphinxcontrib.programoutput",
-    "sphinx_inline_tabs",
     "sphinx_rtd_theme",
 ]
 

doc/configuration.rst

@@ -1,5 +1,3 @@
-.. _configuration:
-
 Configuration
 =============
 
@@ -102,7 +100,6 @@ For example:
 
 ``CAN_INTERFACE=socketcan CAN_CONFIG={"receive_own_messages": true, "fd": true}``
 
-.. _interface names:
 
 Interface Names
 ---------------
@@ -112,51 +109,31 @@ Lookup table of interface names:
 +---------------------+-------------------------------------+
 | Name                | Documentation                       |
 +=====================+=====================================+
-| ``"canalystii"``    | :doc:`interfaces/canalystii`        |
-+---------------------+-------------------------------------+
-| ``"cantact"``       | :doc:`interfaces/cantact`           |
+| ``"socketcan"``     | :doc:`interfaces/socketcan`         |
 +---------------------+-------------------------------------+
-| ``"etas"``          | :doc:`interfaces/etas`              |
+| ``"kvaser"``        | :doc:`interfaces/kvaser`            |
 +---------------------+-------------------------------------+
-| ``"gs_usb"``        | :doc:`interfaces/gs_usb`            |
+| ``"serial"``        | :doc:`interfaces/serial`            |
 +---------------------+-------------------------------------+
-| ``"iscan"``         | :doc:`interfaces/iscan`             |
+| ``"slcan"``         | :doc:`interfaces/slcan`             |
 +---------------------+-------------------------------------+
 | ``"ixxat"``         | :doc:`interfaces/ixxat`             |
 +---------------------+-------------------------------------+
-| ``"kvaser"``        | :doc:`interfaces/kvaser`            |
-+---------------------+-------------------------------------+
-| ``"neousys"``       | :doc:`interfaces/neousys`           |
+| ``"pcan"``          | :doc:`interfaces/pcan`              |
 +---------------------+-------------------------------------+
-| ``"neovi"``         | :doc:`interfaces/neovi`             |
+| ``"usb2can"``       | :doc:`interfaces/usb2can`           |
 +---------------------+-------------------------------------+
 | ``"nican"``         | :doc:`interfaces/nican`             |
 +---------------------+-------------------------------------+
-| ``"nixnet"``        | :doc:`interfaces/nixnet`            |
-+---------------------+-------------------------------------+
-| ``"pcan"``          | :doc:`interfaces/pcan`              |
-+---------------------+-------------------------------------+
-| ``"robotell"``      | :doc:`interfaces/robotell`          |
-+---------------------+-------------------------------------+
-| ``"seeedstudio"``   | :doc:`interfaces/seeedstudio`       |
+| ``"iscan"``         | :doc:`interfaces/iscan`             |
 +---------------------+-------------------------------------+
-| ``"serial"``        | :doc:`interfaces/serial`            |
+| ``"neovi"``         | :doc:`interfaces/neovi`             |
 +---------------------+-------------------------------------+
-| ``"slcan"``         | :doc:`interfaces/slcan`             |
+| ``"vector"``        | :doc:`interfaces/vector`            |
 +---------------------+-------------------------------------+
-| ``"socketcan"``     | :doc:`interfaces/socketcan`         |
+| ``"virtual"``       | :doc:`interfaces/virtual`           |
 +---------------------+-------------------------------------+
-| ``"socketcand"``    | :doc:`interfaces/socketcand`        |
+| ``"canalystii"``    | :doc:`interfaces/canalystii`        |
 +---------------------+-------------------------------------+
 | ``"systec"``        | :doc:`interfaces/systec`            |
 +---------------------+-------------------------------------+
-| ``"udp_multicast"`` | :doc:`interfaces/udp_multicast`     |
-+---------------------+-------------------------------------+
-| ``"usb2can"``       | :doc:`interfaces/usb2can`           |
-+---------------------+-------------------------------------+
-| ``"vector"``        | :doc:`interfaces/vector`            |
-+---------------------+-------------------------------------+
-| ``"virtual"``       | :doc:`interfaces/virtual`           |
-+---------------------+-------------------------------------+
-
-Additional interface types can be added via the :ref:`plugin interface`.

doc/development.rst

@@ -35,16 +35,17 @@ The following assumes that the commands are executed from the root of the reposi
 
 The project can be built with::
 
-    pipx run build
-    pipx run twine check dist/*
+    pip install wheel
+    python setup.py sdist bdist_wheel
 
 The project can be installed in editable mode with::
 
     pip install -e .
 
 The unit tests can be run with::
 
-    pipx run tox -e py
+    pip install tox
+    tox -e py
 
 The documentation can be built with::
 
@@ -78,11 +79,6 @@ These steps are a guideline on how to add a new backend to python-can.
   To get started, have a look at ``back2back_test.py``:
   Simply add a test case like ``BasicTestSocketCan`` and some basic tests will be executed for the new interface.
 
-.. attention::
-    We strongly recommend using the :ref:`plugin interface` to extend python-can.
-    Publish a python package that contains your :class:`can.BusABC` subclass and use
-    it within the python-can API. We will mention your package inside this documentation
-    and add it as an optional dependency.
 
 Code Structure
 --------------

doc/doc-requirements.txt

@@ -1,4 +1,3 @@
 sphinx>=5.2.3
 sphinxcontrib-programoutput
 sphinx_rtd_theme
-sphinx-inline-tabs

doc/interfaces.rst

@@ -1,5 +1,3 @@
-.. _can interface modules:
-
 CAN Interface Modules
 ---------------------
 
@@ -14,13 +12,11 @@ The available interfaces are:
    :maxdepth: 1
 
    interfaces/canalystii
-   interfaces/cantact
    interfaces/etas
    interfaces/gs_usb
    interfaces/iscan
    interfaces/ixxat
    interfaces/kvaser
-   interfaces/neousys
    interfaces/neovi
    interfaces/nican
    interfaces/nixnet
@@ -37,58 +33,19 @@ The available interfaces are:
    interfaces/vector
    interfaces/virtual
 
-The *Interface Names* are listed in :doc:`configuration`.
-
-
-.. _plugin interface:
-
-Plugin Interface
-^^^^^^^^^^^^^^^^
-
-External packages can register a new interfaces by using the ``can.interface`` entry point
-in its project configuration. The format of the entry point depends on your project
-configuration format (*pyproject.toml*, *setup.cfg* or *setup.py*).
-
-In the following example ``module`` defines the location of your bus class inside your
-package e.g. ``my_package.subpackage.bus_module`` and ``classname`` is the name of
-your :class:`can.BusABC` subclass.
-
-.. tab:: pyproject.toml (PEP 621)
-
-   .. code-block:: toml
+Additional interfaces can be added via a plugin interface. An external package
+can register a new interface by using the ``can.interface`` entry point in its setup.py.
 
-        # Note the quotes around can.interface in order to escape the dot .
-        [project.entry-points."can.interface"]
-        interface_name = "module:classname"
+The format of the entry point is ``interface_name=module:classname`` where
+``classname`` is a concrete :class:`can.BusABC` implementation.
 
-.. tab:: setup.cfg
+::
 
-   .. code-block:: ini
+ entry_points={
+     'can.interface': [
+         "interface_name=module:classname",
+     ]
+ },
 
-        [options.entry_points]
-        can.interface =
-            interface_name = module:classname
 
-.. tab:: setup.py
-
-   .. code-block:: python
-
-        from setuptools import setup
-
-        setup(
-            # ...,
-            entry_points = {
-                'can.interface': [
-                    'interface_name = module:classname'
-                ]
-            }
-        )
-
-The ``interface_name`` can be used to
-create an instance of the bus in the **python-can** API:
-
-.. code-block:: python
-
-    import can
-
-    bus = can.Bus(interface="interface_name", channel=0)
+The *Interface Names* are listed in :doc:`configuration`.