Repository: mdabrowski1990/uds (language: python)

Issue:
[INVESTIGATE] Add doc8 as sphinx documentation checker
# Description
As a developer, I would love to have automated checks for sphinx documentation.

# Testing
- CI/CD is passing

# Acceptance Criteria
- investigate whether [doc8](https://github.com/PyCQA/doc8) can be added to existing CI/CD
- [optional] add [doc8](https://github.com/PyCQA/doc8) checks to CI/CD workflows
  - rework documentation to pass these checks


Discussion / hints:

Fix patch:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 80475846..f53a6e8c 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,11 +1,11 @@
-## Description
+# Description
 <!--- Describe your changes -->
 
 
-## How Has This Been Tested?
+# How Has This Been Tested?
 <!--- Please shortly describe how you tested your code. -->
 
 
-## Process
+# Process
 <!--- If you are familiar with the process, leave the line below. If not, please describe what you did, so we could help you deliver your changed according to our quality policies -->
 I know the [process](https://github.com/mdabrowski1990/uds/wiki/Software-Development-Life-Cycle) and did my best to follow it
diff --git a/docs/source/pages/knowledge_base/diagnostic_message.rst b/docs/source/pages/knowledge_base/diagnostic_message.rst
index a96ea608..88724e7b 100644
--- a/docs/source/pages/knowledge_base/diagnostic_message.rst
+++ b/docs/source/pages/knowledge_base/diagnostic_message.rst
@@ -231,8 +231,9 @@ in one or multiple servers' memory.
 ReadDTCInformation
 ``````````````````
 ReadDTCInformation service allows the client to read from any server or group of servers within a vehicle,
-current information about all Diagnostic Trouble Codes. This could be a status of reported Diagnostic Trouble Code (DTC),
-number of currently active DTCs or any other information returned by supported ReadDTCInformation SubFunctions.
+current information about all Diagnostic Trouble Codes.
+This could be a status of reported Diagnostic Trouble Code (DTC), number of currently active DTCs or any other
+information returned by supported ReadDTCInformation SubFunctions.
 
 
 ReadDataByIdentifier
diff --git a/docs/source/pages/knowledge_base/packet.rst b/docs/source/pages/knowledge_base/packet.rst
index d6ec6cb9..45ab6624 100644
--- a/docs/source/pages/knowledge_base/packet.rst
+++ b/docs/source/pages/knowledge_base/packet.rst
@@ -196,8 +196,8 @@ where:
 Extended Addressing
 '''''''''''''''''''
 If extended addressing format is used, then the value of **the first CAN frame byte informs about a target** of
-a UDS packet and remaining `Network Address Information`_ (a sending entity and :ref:`an addressing type <knowledge-base-addressing>`)
-are determined by CAN Identifier value.
+a UDS packet and remaining `Network Address Information`_ (a sending entity and
+:ref:`an addressing type <knowledge-base-addressing>`) are determined by CAN Identifier value.
 
 Following parameters specifies `Network Address Information`_ when Extended Addressing is used:
  - CAN ID
@@ -402,7 +402,8 @@ Number of payload bytes carried by SF is specified by
 Single Frame Data Length
 ........................
 Single Frame Data Length (SF_DL) is 4-bit (for CAN packets with DLC<=8) or 8-bit (for CAN packets with DLC>8) value
-carried by every Single Frame as presented in :ref:`the table with CAN packet formats<knowledge-base-can-packets-format>`.
+carried by every Single Frame as presented in
+:ref:`the table with CAN packet formats<knowledge-base-can-packets-format>`.
 SF_DL specifies number of diagnostic message payload bytes transmitted in a Single Frame.
 
 .. note:: Maximal value of SF_DL depends on Single Frame :ref:`addressing format <knowledge-base-can-addressing>`
@@ -534,8 +535,9 @@ Block Size (BS) is a one byte value specified by receiving entity that informs a
 Block Size values:
  - 0x00
 
-    The value 0 of the Block Size parameter informs a sender that no more :ref:`Flow Control <knowledge-base-can-flow-control>`
-    frames shall be sent during the transmission of the segmented message.
+    The value 0 of the Block Size parameter informs a sender that no more
+    :ref:`Flow Control <knowledge-base-can-flow-control>` frames shall be sent during the transmission
+    of the segmented message.
 
     Reception of Block Size = 0 shall cause the sender to send all remaining
     :ref:`Consecutive Frames <knowledge-base-can-consecutive-frame>` without any stop for further
diff --git a/docs/source/pages/knowledge_base/performance.rst b/docs/source/pages/knowledge_base/performance.rst
index 0ceecab3..d04e0d1a 100644
--- a/docs/source/pages/knowledge_base/performance.rst
+++ b/docs/source/pages/knowledge_base/performance.rst
@@ -42,8 +42,8 @@ Timeout value:
   1000 ms
 
 Error handling:
-  If N_As timeout is exceeded, then the transmission of the :ref:`diagnostic message <knowledge-base-diagnostic-message>`
-  shall be aborted.
+  If N_As timeout is exceeded, then the transmission of
+  the :ref:`diagnostic message <knowledge-base-diagnostic-message>` shall be aborted.
 
 Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
   - :ref:`Single Frame <knowledge-base-can-single-frame>`
@@ -75,10 +75,10 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Bs
 ````
 N_Bs is a time parameter related to :ref:`Flow Control (CAN Packet) <knowledge-base-can-flow-control>` reception
-by a sender.
-It is measured from the end of the last CAN Packet transmission (either transmitted :ref:`First Frame <knowledge-base-can-first-frame>`,
-:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` or received :ref:`Flow Control <knowledge-base-can-flow-control>`),
-till the reception of :ref:`Flow Control <knowledge-base-can-flow-control>`.
+by a sender. It is measured from the end of the last CAN Packet transmission (either transmitted
+:ref:`First Frame <knowledge-base-can-first-frame>`, :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`
+or received :ref:`Flow Control <knowledge-base-can-flow-control>`), till the reception of
+:ref:`Flow Control <knowledge-base-can-flow-control>`.
 
 Timeout value:
   1000 ms
@@ -96,10 +96,10 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Br
 ````
 N_Br is a time parameter related to :ref:`Flow Control (CAN Packet) <knowledge-base-can-flow-control>` transmission
-by a receiver.
-It is measured from the end of the last CAN Packet transmission (either received :ref:`First Frame <knowledge-base-can-first-frame>`,
-:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` or transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`),
-till the start of :ref:`Flow Control <knowledge-base-can-flow-control>` transmission.
+by a receiver. It is measured from the end of the last CAN Packet transmission (either received
+:ref:`First Frame <knowledge-base-can-first-frame>`, :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`
+or transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`), till the start of
+:ref:`Flow Control <knowledge-base-can-flow-control>` transmission.
 
 Performance requirement:
   A receiving entity is obliged to transmit :ref:`Flow Control <knowledge-base-can-flow-control>` packet before value
@@ -119,9 +119,9 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Cs
 ````
 N_Cs is a time parameter related to :ref:`Consecutive Frame (CAN Packet) <knowledge-base-can-consecutive-frame>`
-transmission by a sender.
-It is measured from the end of the last CAN Packet transmission (either received :ref:`Flow Control <knowledge-base-can-flow-control>`
-or transmitted :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the start of
+transmission by a sender. It is measured from the end of the last CAN Packet transmission (either received
+:ref:`Flow Control <knowledge-base-can-flow-control>` or transmitted
+:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the start of
 :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>` transmission.
 
 Performance requirement:
@@ -142,9 +142,9 @@ Affected :ref:`CAN Packets <knowledge-base-uds-can-packet>`:
 N_Cr
 ````
 N_Cr is a time parameter related to :ref:`Consecutive Frame (CAN Packet) <knowledge-base-can-consecutive-frame>`
-reception by a receiver.
-It is measured from the end of the last CAN Packet transmission (either transmitted :ref:`Flow Control <knowledge-base-can-flow-control>`
-or received :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the reception of
+reception by a receiver. It is measured from the end of the last CAN Packet transmission (either transmitted
+:ref:`Flow Control <knowledge-base-can-flow-control>` or received
+:ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`), till the reception of
 :ref:`Consecutive Frame <knowledge-base-can-consecutive-frame>`.
 
 Timeout value:
diff --git a/docs/source/pages/user_guide/client_simulation.rst b/docs/source/pages/user_guide/client_simulation.rst
index 9d32557e..71af6a52 100644
--- a/docs/source/pages/user_guide/client_simulation.rst
+++ b/docs/source/pages/user_guide/client_simulation.rst
@@ -5,4 +5,4 @@ ECUs) in UDS communication. Client simulation enables sending diagnostic request
 from connected nodes.
 
 `THIS FEATURE <https://github.com/mdabrowski1990/uds/milestone/8>`_ IS PLANNED BUT NOT IMPLEMENTED YET,
-THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/docs/source/pages/user_guide/segmentation.rst b/docs/source/pages/user_guide/segmentation.rst
index d204368c..86dfe3cb 100644
--- a/docs/source/pages/user_guide/segmentation.rst
+++ b/docs/source/pages/user_guide/segmentation.rst
@@ -87,7 +87,8 @@ Following functionalities are provided by :class:`~uds.segmentation.can_segmente
 - CAN packets desegmentation:
 
   As a user, you are able to :ref:`desegment CAN packets <knowledge-base-packets-desegmentation>`
-  (either objects of :class:`~uds.packet.can_packet.CanPacket` or :class:`~uds.packet.can_packet_record.CanPacketRecord` class)
+  (either objects of :class:`~uds.packet.can_packet.CanPacket` or
+  :class:`~uds.packet.can_packet_record.CanPacketRecord` class)
   into diagnostic messages (either objects of :class:`~uds.message.uds_message.UdsMessage` or
   :class:`~uds.message.uds_message.UdsMessageRecord` class).
 
diff --git a/docs/source/pages/user_guide/transport.rst b/docs/source/pages/user_guide/transport.rst
index 2260c0af..60e5f165 100644
--- a/docs/source/pages/user_guide/transport.rst
+++ b/docs/source/pages/user_guide/transport.rst
@@ -2,8 +2,8 @@ Transport Interfaces
 ====================
 Transport interfaces are meant to handle Physical (layer 1), Data (layer 2), Network (layer 3) and Transport (layer 4)
 layers of UDS OSI model which are unique for every communication bus. First two layers (Physical and Data Link) are
-usually handled by some external packages. Abstract API that is common for all Transport Interfaces (and therefore buses)
-is defined in :class:`~uds.transport_interface.abstract_transport_interface.AbstractTransportInterface` class.
+usually handled by some external packages. Abstract API that is common for all Transport Interfaces (and therefore
+buses) is defined in :class:`~uds.transport_interface.abstract_transport_interface.AbstractTransportInterface` class.
 The implementation is located in :mod:`uds.transport_interface` sub-package.
 
 .. toctree::
diff --git a/docs/source/pages/user_guide/transport/can.rst b/docs/source/pages/user_guide/transport/can.rst
index d57c2933..a34c451a 100644
--- a/docs/source/pages/user_guide/transport/can.rst
+++ b/docs/source/pages/user_guide/transport/can.rst
@@ -38,7 +38,8 @@ The following configuration parameters are set then:
   :attr:`~uds.transport_interface.can_transport_interface.AbstractCanTransportInterface.use_data_optimization`,
   :attr:`~uds.transport_interface.can_transport_interface.AbstractCanTransportInterface.filler_byte`,
 
-Most of these attributes (all except :attr:`~uds.transport_interface.can_transport_interface.AbstractCanTransportInterface.addressing_information`)
+Most of these attributes (all except
+:attr:`~uds.transport_interface.can_transport_interface.AbstractCanTransportInterface.addressing_information`)
 can be changed after object is created.
 
 
@@ -160,8 +161,8 @@ there are two methods which can be used to receive CAN packets:
 
 - :meth:`~uds.transport_interface.can_transport_interface.PyCanTransportInterface.receive_packet` - for synchronous
   implementation
-- :meth:`~uds.transport_interface.can_transport_interface.PyCanTransportInterface.async_receive_packet` - for asynchronous
-  implementation
+- :meth:`~uds.transport_interface.can_transport_interface.PyCanTransportInterface.async_receive_packet` - for
+  asynchronous implementation
 
 **Example synchronous code:**
 
diff --git a/docs/source/pages/user_guide/transport/custom.rst b/docs/source/pages/user_guide/transport/custom.rst
index ad481d6f..abadeec8 100644
--- a/docs/source/pages/user_guide/transport/custom.rst
+++ b/docs/source/pages/user_guide/transport/custom.rst
@@ -1,3 +1,3 @@
 Custom Transport Interfaces
 ===========================
-THIS FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+THIS FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/docs/source/pages/user_guide/transport/ethernet.rst b/docs/source/pages/user_guide/transport/ethernet.rst
index 79e9a7f5..d1fa1090 100644
--- a/docs/source/pages/user_guide/transport/ethernet.rst
+++ b/docs/source/pages/user_guide/transport/ethernet.rst
@@ -1,3 +1,3 @@
 Ethernet Transport Interfaces
 =============================
-Ethernet FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+Ethernet FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/docs/source/pages/user_guide/transport/flexray.rst b/docs/source/pages/user_guide/transport/flexray.rst
index cae2022b..a087eb08 100644
--- a/docs/source/pages/user_guide/transport/flexray.rst
+++ b/docs/source/pages/user_guide/transport/flexray.rst
@@ -1,3 +1,3 @@
 FlexRay Transport Interfaces
 ============================
-FlexRay FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+FlexRay FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/docs/source/pages/user_guide/transport/kline.rst b/docs/source/pages/user_guide/transport/kline.rst
index c6d50adc..95109594 100644
--- a/docs/source/pages/user_guide/transport/kline.rst
+++ b/docs/source/pages/user_guide/transport/kline.rst
@@ -1,3 +1,3 @@
 K-Line Transport Interfaces
 ===========================
-K-Line FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+K-Line FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/docs/source/pages/user_guide/transport/lin.rst b/docs/source/pages/user_guide/transport/lin.rst
index dbb6ef8c..03907c2e 100644
--- a/docs/source/pages/user_guide/transport/lin.rst
+++ b/docs/source/pages/user_guide/transport/lin.rst
@@ -1,3 +1,3 @@
 LIN Transport Interfaces
 ========================
-LIN FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
\ No newline at end of file
+LIN FEATURE IS PLANNED BUT NOT IMPLEMENTED YET, THEREFORE THERE ARE NO MORE INFORMATION TO DISPLAY.
diff --git a/pyproject.toml b/pyproject.toml
index d086adb8..cb877a9b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,12 +66,6 @@ test = [
     "pytest-cov",
     "pytest-asyncio",
 ]
-docs = [
-    "sphinx",
-    "sphinx-autoapi",
-    "sphinx-rtd-theme",
-    "tomli",
-]
 static-code-analysis = [
     "prospector == 1.10.3",
     "mypy == 1.9.0",
@@ -86,6 +80,15 @@ dependency-scan = [
 sorting-imports = [
     "isort == 5.13.2"
 ]
+docs = [
+    "sphinx",
+    "sphinx-autoapi",
+    "sphinx-rtd-theme",
+    "tomli",
+]
+docs-checks = [
+    "doc8 == 1.1.1",
+]
 
 
 [build-system]
@@ -143,4 +146,12 @@ line_length = 120
 use_parentheses = true
 include_trailing_comma = true
 force_grid_wrap = 0
-multi_line_output = 3
\ No newline at end of file
+multi_line_output = 3
+
+
+[tool.doc8]
+max-line-length = 120
+ignore = ["D004"]
+ignore-path-errors = [
+    "docs\\source\\pages\\knowledge_base\\diagnostic_message.rst;D001",  # tables
+]


Test patch:
diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml
index a9c58daf..de8bef21 100644
--- a/.github/workflows/testing.yml
+++ b/.github/workflows/testing.yml
@@ -178,7 +178,7 @@ jobs:
           python -m pip install --upgrade setuptools
           pip install -r requirements.txt
 
-      - name: Install external packages used for dynamic tests
+      - name: Install external packages used for sorting imports
         run: |
           pip install .[sorting-imports]
 
@@ -187,3 +187,26 @@ jobs:
           isort uds
           isort tests
           isort examples
+
+  documentation_checks:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.12
+
+      - name: Install project dependencies
+        run: |
+          pip install -r requirements.txt
+
+      - name: Install external packages used for documentation checking
+        run: |
+          pip install .[docs-checks]
+
+      - name: Check RST documentation [doc8]
+        run: |
+          doc8 docs\source