Fix Sphinx warnings (hardbyte#1405)

* fix most sphinx warnings

* build docs in CI

* install package

* fix extlink caption string deprecation warning

* add Seeed Studio to title

* update readthedocs configuration

* add mocks for windows specifics

* mypy should ignore conf.py

* upload sphinx artifact

* set retention to 5 days

* set type annotation location

.github/workflows/build.yml

@@ -87,3 +87,25 @@ 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

@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+  - epub
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - requirements: doc/doc-requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - canalystii
+        - gs_usb

can/broadcastmanager.py

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

can/bus.py

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

can/exceptions.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 :class:`can.CanInterfaceNotImplementedError` is raised instead.
+    a :exc:`~can.exceptions.CanInterfaceNotImplementedError` is raised instead.
     If initialization fails due to a value being out of range, a :class:`ValueError`
     is raised.
 

can/interfaces/ixxat/canlib_vcinpl.py

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

can/interfaces/ixxat/canlib_vcinpl2.py

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

can/interfaces/kvaser/canlib.py

@@ -657,7 +657,7 @@ def shutdown(self):
         canBusOff(self._write_handle)
         canClose(self._write_handle)
 
-    def get_stats(self):
+    def get_stats(self) -> structures.BusStatistics:
         """Retrieves the bus statistics.
 
         Use like so:
@@ -667,7 +667,6 @@ def get_stats(self):
         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/structures.py

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

can/interfaces/nican.py

@@ -179,10 +179,8 @@ class NicanBus(BusABC):
     .. warning::
 
         This interface does implement efficient filtering of messages, but
-        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.
-
+        the filters have to be set in ``__init__`` using the ``can_filters`` parameter.
+        Using :meth:`~can.BusABC.set_filters` does not work.
     """
 
     def __init__(
@@ -208,9 +206,9 @@ def __init__(
             ``is_error_frame`` set to True and ``arbitration_id`` will identify
             the error (default True)
 
-        :raise can.CanInterfaceNotImplementedError:
+        :raise ~can.exceptions.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/pcan/pcan.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:`~can.interface.pcan.PcanBus.flash`
-        and :meth:`~can.interface.pcan.PcanBus.status` methods.
+        the PCAN interface includes the :meth:`flash`
+        and :meth:`status` methods.
 
         :param str channel:
             The can interface name. An example would be 'PCAN_USBBUS1'.

can/interfaces/robotell.py

@@ -5,9 +5,10 @@
 import io
 import time
 import logging
+from typing import Optional
 
 from can import BusABC, Message
-from ..exceptions import CanInterfaceNotImplementedError
+from ..exceptions import CanInterfaceNotImplementedError, CanOperationError
 
 logger = logging.getLogger(__name__)
 
@@ -377,12 +378,11 @@ def fileno(self):
         except Exception as exception:
             raise CanOperationError("Cannot fetch fileno") from exception
 
-    def get_serial_number(self, timeout):
+    def get_serial_number(self, timeout: Optional[int]) -> Optional[str]:
         """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/serial/serial_can.py

@@ -74,8 +74,10 @@ def __init__(
         :param rtscts:
             turn hardware handshake (RTS/CTS) on and off
 
-        :raises can.CanInitializationError: If the given parameters are invalid.
-        :raises can.CanInterfaceNotImplementedError: If the serial module is not installed.
+        :raises ~can.exceptions.CanInitializationError:
+            If the given parameters are invalid.
+        :raises ~can.exceptions.CanInterfaceNotImplementedError:
+            If the serial module is not installed.
         """
 
         if not serial:
@@ -163,10 +165,10 @@ def _recv_internal(
                 This parameter will be ignored. The timeout value of the channel is used.
 
         :returns:
-            Received message and `False` (because no filtering as taken place).
+            Received message and :obj:`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/slcan.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 ``None`` to wait indefinitely
+            seconds to wait for serial number or :obj:`None` to wait indefinitely
 
         :return:
-            ``None`` on timeout or a :class:`~builtin.str` object.
+            :obj:`None` on timeout or a :class:`str` object.
         """
         cmd = "N"
         self._write(cmd)

can/interfaces/socketcan/socketcan.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 :attr:`~task_id` identifier. The message length
+        with the specified ``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 :attr:`~task_id` is already running.
+            If the task referenced by ``task_id`` is already running.
         """
         self._tx_setup(self.messages)
 
@@ -617,9 +617,10 @@ 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.
@@ -739,7 +740,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.CanError:
+        :raises ~can.exceptions.CanError:
             if the message could not be written.
         """
         log.debug("We've been asked to write a message to the bus")

can/interfaces/systec/ucanbus.py

@@ -88,10 +88,10 @@ def __init__(self, channel, can_filters=None, **kwargs):
         :raises ValueError:
             If invalid input parameter were passed.
 
-        :raises can.CanInterfaceNotImplementedError:
+        :raises ~can.exceptions.CanInterfaceNotImplementedError:
             If the platform is not supported.
 
-        :raises can.CanInitializationError:
+        :raises ~can.exceptions.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.CanOperationError:
+        :raises ~can.exceptions.CanOperationError:
             If the message could not be sent.
         """
         try:
@@ -243,7 +243,7 @@ def flush_tx_buffer(self):
         """
         Flushes the transmit buffer.
 
-        :raises can.CanError:
+        :raises ~can.exceptions.CanError:
             If flushing of the transmit buffer failed.
         """
         log.info("Flushing transmit buffer")