Revert "Fix Sphinx warnings (hardbyte#1405)"

This reverts commit 451ce48.

Author: j-c-cook

.github/workflows/build.yml

@@ -87,25 +87,3 @@ jobs:
     - name: Code Format Check with Black
       run: |
         black --check --verbose .
-
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: "3.10"
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e .[canalystii,gs_usb]
-        pip install -r doc/doc-requirements.txt
-    - name: Build documentation
-      run: |
-        python -m sphinx -an doc build
-    - uses: actions/upload-artifact@v3
-      with:
-        name: sphinx-out
-        path: ./build/
-        retention-days: 5

.readthedocs.yml

@@ -39,7 +39,7 @@ class CyclicTask(abc.ABC):
     def stop(self) -> None:
         """Cancel this periodic task.
 
-        :raises ~can.exceptions.CanError:
+        :raises can.CanError:
             If stop is called on an already stopped task.
         """
 

can/broadcastmanager.py

@@ -66,10 +66,8 @@ def __init__(
             Any backend dependent configurations are passed in this dictionary
 
         :raises ValueError: If parameters are out of range
-        :raises ~can.exceptions.CanInterfaceNotImplementedError:
-            If the driver cannot be accessed
-        :raises ~can.exceptions.CanInitializationError:
-            If the bus cannot be initialized
+        :raises can.CanInterfaceNotImplementedError: If the driver cannot be accessed
+        :raises can.CanInitializationError: If the bus cannot be initialized
         """
         self._periodic_tasks: List[_SelfRemovingCyclicTask] = []
         self.set_filters(can_filters)
@@ -83,11 +81,9 @@ def recv(self, timeout: Optional[float] = None) -> Optional[Message]:
         :param timeout:
             seconds to wait for a message or None to wait indefinitely
 
-        :return:
-            :obj:`None` on timeout or a :class:`~can.Message` object.
+        :return: ``None`` on timeout or a :class:`Message` object.
 
-        :raises ~can.exceptions.CanOperationError:
-            If an error occurred while reading
+        :raises can.CanOperationError: If an error occurred while reading
         """
         start = time()
         time_left = timeout
@@ -152,8 +148,7 @@ def _recv_internal(
             2.  a bool that is True if message filtering has already
                 been done and else False
 
-        :raises ~can.exceptions.CanOperationError:
-            If an error occurred while reading
+        :raises can.CanOperationError: If an error occurred while reading
         :raises NotImplementedError:
             if the bus provides it's own :meth:`~can.BusABC.recv`
             implementation (legacy implementation)
@@ -176,8 +171,7 @@ def send(self, msg: Message, timeout: Optional[float] = None) -> None:
             Might not be supported by all interfaces.
             None blocks indefinitely.
 
-        :raises ~can.exceptions.CanOperationError:
-            If an error occurred while sending
+        :raises can.CanOperationError: If an error occurred while sending
         """
         raise NotImplementedError("Trying to write to a readonly bus?")
 
@@ -195,8 +189,8 @@ def send_periodic(
         - the (optional) duration expires
         - the Bus instance goes out of scope
         - the Bus instance is shutdown
-        - :meth:`stop_all_periodic_tasks` is called
-        - the task's :meth:`~can.broadcastmanager.CyclicTask.stop` method is called.
+        - :meth:`BusABC.stop_all_periodic_tasks()` is called
+        - the task's :meth:`CyclicTask.stop()` method is called.
 
         :param msgs:
             Message(s) to transmit
@@ -210,8 +204,7 @@ def send_periodic(
             Disable to instead manage tasks manually.
         :return:
             A started task instance. Note the task can be stopped (and depending on
-            the backend modified) by calling the task's
-            :meth:`~can.broadcastmanager.CyclicTask.stop` method.
+            the backend modified) by calling the task's :meth:`stop` method.
 
         .. note::
 
@@ -281,8 +274,8 @@ def _send_periodic_internal(
             no duration is provided, the task will continue indefinitely.
         :return:
             A started task instance. Note the task can be stopped (and
-            depending on the backend modified) by calling the
-            :meth:`~can.broadcastmanager.CyclicTask.stop` method.
+            depending on the backend modified) by calling the :meth:`stop`
+            method.
         """
         if not hasattr(self, "_lock_send_periodic"):
             # Create a send lock for this bus, but not for buses which override this method
@@ -295,7 +288,7 @@ def _send_periodic_internal(
         return task
 
     def stop_all_periodic_tasks(self, remove_tasks: bool = True) -> None:
-        """Stop sending any messages that were started using :meth:`send_periodic`.
+        """Stop sending any messages that were started using **bus.send_periodic**.
 
         .. note::
             The result is undefined if a single task throws an exception while being stopped.

can/bus.py

@@ -74,7 +74,7 @@ class CanInitializationError(CanError):
     """Indicates an error the occurred while initializing a :class:`can.BusABC`.
 
     If initialization fails due to a driver or platform missing/being unsupported,
-    a :exc:`~can.exceptions.CanInterfaceNotImplementedError` is raised instead.
+    a :class:`can.CanInterfaceNotImplementedError` is raised instead.
     If initialization fails due to a value being out of range, a :class:`ValueError`
     is raised.
 

can/exceptions.py

@@ -372,8 +372,10 @@ class IXXATBus(BusABC):
     .. warning::
 
         This interface does implement efficient filtering of messages, but
-        the filters have to be set in ``__init__`` using the ``can_filters`` parameter.
-        Using :meth:`~can.BusABC.set_filters` does not work.
+        the filters have to be set in :meth:`~can.interfaces.ixxat.IXXATBus.__init__`
+        using the ``can_filters`` parameter. Using :meth:`~can.interfaces.ixxat.IXXATBus.set_filters`
+        does not work.
+
     """
 
     CHANNEL_BITRATES = {

can/interfaces/ixxat/canlib_vcinpl.py

@@ -411,8 +411,9 @@ class IXXATBus(BusABC):
     .. warning::
 
         This interface does implement efficient filtering of messages, but
-        the filters have to be set in ``__init__`` using the ``can_filters`` parameter.
-        Using :meth:`~can.BusABC.set_filters` does not work.
+        the filters have to be set in :meth:`~can.interfaces.ixxat.IXXATBus.__init__`
+        using the ``can_filters`` parameter. Using :meth:`~can.interfaces.ixxat.IXXATBus.set_filters`
+        does not work.
 
     """
 

can/interfaces/ixxat/canlib_vcinpl2.py

@@ -657,7 +657,7 @@ def shutdown(self):
         canBusOff(self._write_handle)
         canClose(self._write_handle)
 
-    def get_stats(self) -> structures.BusStatistics:
+    def get_stats(self):
         """Retrieves the bus statistics.
 
         Use like so:
@@ -667,6 +667,7 @@ def get_stats(self) -> structures.BusStatistics:
         std_data: 0, std_remote: 0, ext_data: 0, ext_remote: 0, err_frame: 0, bus_load: 0.0%, overruns: 0
 
         :returns: bus statistics.
+        :rtype: can.interfaces.kvaser.structures.BusStatistics
         """
         canRequestBusStatistics(self._write_handle)
         stats = structures.BusStatistics()

can/interfaces/kvaser/canlib.py

@@ -7,8 +7,11 @@
 
 
 class BusStatistics(ctypes.Structure):
-    """This structure is used with the method
-    :meth:`~can.interfaces.kvaser.canlib.KvaserBus.get_stats`.
+    """
+    This structure is used with the method :meth:`KvaserBus.get_stats`.
+
+     .. seealso:: :meth:`KvaserBus.get_stats`
+
     """
 
     _fields_ = [

can/interfaces/kvaser/structures.py

@@ -179,8 +179,10 @@ class NicanBus(BusABC):
     .. warning::
 
         This interface does implement efficient filtering of messages, but
-        the filters have to be set in ``__init__`` using the ``can_filters`` parameter.
-        Using :meth:`~can.BusABC.set_filters` does not work.
+        the filters have to be set in :meth:`~can.interfaces.nican.NicanBus.__init__`
+        using the ``can_filters`` parameter. Using :meth:`~can.interfaces.nican.NicanBus.set_filters`
+        does not work.
+
     """
 
     def __init__(
@@ -206,9 +208,9 @@ def __init__(
             ``is_error_frame`` set to True and ``arbitration_id`` will identify
             the error (default True)
 
-        :raise ~can.exceptions.CanInterfaceNotImplementedError:
+        :raise can.CanInterfaceNotImplementedError:
             If the current operating system is not supported or the driver could not be loaded.
-        :raise ~can.interfaces.nican.NicanInitializationError:
+        :raise can.interfaces.nican.NicanInitializationError:
             If the bus could not be set up.
         """
         if nican is None:

can/interfaces/nican.py

@@ -113,8 +113,8 @@ def __init__(
         """A PCAN USB interface to CAN.
 
         On top of the usual :class:`~can.Bus` methods provided,
-        the PCAN interface includes the :meth:`flash`
-        and :meth:`status` methods.
+        the PCAN interface includes the :meth:`~can.interface.pcan.PcanBus.flash`
+        and :meth:`~can.interface.pcan.PcanBus.status` methods.
 
         :param str channel:
             The can interface name. An example would be 'PCAN_USBBUS1'.

can/interfaces/pcan/pcan.py

@@ -5,10 +5,9 @@
 import io
 import time
 import logging
-from typing import Optional
 
 from can import BusABC, Message
-from ..exceptions import CanInterfaceNotImplementedError, CanOperationError
+from ..exceptions import CanInterfaceNotImplementedError
 
 logger = logging.getLogger(__name__)
 
@@ -378,11 +377,12 @@ def fileno(self):
         except Exception as exception:
             raise CanOperationError("Cannot fetch fileno") from exception
 
-    def get_serial_number(self, timeout: Optional[int]) -> Optional[str]:
+    def get_serial_number(self, timeout):
         """Get serial number of the slcan interface.
-
+        :type timeout: int or None
         :param timeout:
             seconds to wait for serial number or None to wait indefinitely
+        :rtype str or None
         :return:
             None on timeout or a str object.
         """

can/interfaces/robotell.py

@@ -74,10 +74,8 @@ def __init__(
         :param rtscts:
             turn hardware handshake (RTS/CTS) on and off
 
-        :raises ~can.exceptions.CanInitializationError:
-            If the given parameters are invalid.
-        :raises ~can.exceptions.CanInterfaceNotImplementedError:
-            If the serial module is not installed.
+        :raises can.CanInitializationError: If the given parameters are invalid.
+        :raises can.CanInterfaceNotImplementedError: If the serial module is not installed.
         """
 
         if not serial:
@@ -165,10 +163,10 @@ def _recv_internal(
                 This parameter will be ignored. The timeout value of the channel is used.
 
         :returns:
-            Received message and :obj:`False` (because no filtering as taken place).
+            Received message and `False` (because no filtering as taken place).
 
             .. warning::
-                Flags like ``is_extended_id``, ``is_remote_frame`` and ``is_error_frame``
+                Flags like is_extended_id, is_remote_frame and is_error_frame
                 will not be set over this function, the flags in the return
                 message are the default values.
         """

can/interfaces/serial/serial_can.py

@@ -323,10 +323,10 @@ def get_serial_number(self, timeout: Optional[float]) -> Optional[str]:
         """Get serial number of the slcan interface.
 
         :param timeout:
-            seconds to wait for serial number or :obj:`None` to wait indefinitely
+            seconds to wait for serial number or ``None`` to wait indefinitely
 
         :return:
-            :obj:`None` on timeout or a :class:`str` object.
+            ``None`` on timeout or a :class:`~builtin.str` object.
         """
         cmd = "N"
         self._write(cmd)

can/interfaces/slcan.py

@@ -402,7 +402,7 @@ def stop(self) -> None:
         """Stop a task by sending TX_DELETE message to Linux kernel.
 
         This will delete the entry for the transmission of the CAN-message
-        with the specified ``task_id`` identifier. The message length
+        with the specified :attr:`~task_id` identifier. The message length
         for the command TX_DELETE is {[bcm_msg_head]} (only the header).
         """
         log.debug("Stopping periodic task")
@@ -444,7 +444,7 @@ def start(self) -> None:
         message to Linux kernel prior to scheduling.
 
         :raises ValueError:
-            If the task referenced by ``task_id`` is already running.
+            If the task referenced by :attr:`~task_id` is already running.
         """
         self._tx_setup(self.messages)
 
@@ -617,10 +617,9 @@ def __init__(
 
         If setting some socket options fails, an error will be printed but no exception will be thrown.
         This includes enabling:
-
-            - that own messages should be received,
-            - CAN-FD frames and
-            - error frames.
+         - that own messages should be received,
+         - CAN-FD frames and
+         - error frames.
 
         :param channel:
             The can interface name with which to create this bus.
@@ -740,7 +739,7 @@ def send(self, msg: Message, timeout: Optional[float] = None) -> None:
             Wait up to this many seconds for the transmit queue to be ready.
             If not given, the call may fail immediately.
 
-        :raises ~can.exceptions.CanError:
+        :raises can.CanError:
             if the message could not be written.
         """
         log.debug("We've been asked to write a message to the bus")

can/interfaces/socketcan/socketcan.py

@@ -88,10 +88,10 @@ def __init__(self, channel, can_filters=None, **kwargs):
         :raises ValueError:
             If invalid input parameter were passed.
 
-        :raises ~can.exceptions.CanInterfaceNotImplementedError:
+        :raises can.CanInterfaceNotImplementedError:
             If the platform is not supported.
 
-        :raises ~can.exceptions.CanInitializationError:
+        :raises can.CanInitializationError:
             If hardware or CAN interface initialization failed.
         """
         try:
@@ -181,7 +181,7 @@ def send(self, msg, timeout=None):
         :param float timeout:
             Transmit timeout in seconds (value 0 switches off the "auto delete")
 
-        :raises ~can.exceptions.CanOperationError:
+        :raises can.CanOperationError:
             If the message could not be sent.
         """
         try:
@@ -243,7 +243,7 @@ def flush_tx_buffer(self):
         """
         Flushes the transmit buffer.
 
-        :raises ~can.exceptions.CanError:
+        :raises can.CanError:
             If flushing of the transmit buffer failed.
         """
         log.info("Flushing transmit buffer")