Add code example to BitTiming docs (#1515)

* add copy button

* make bittiming classes hashable

* add code example to show possible bit timings

* fix tests

* rename variable

Author: zariiii9003

can/bit_timing.py

@@ -395,14 +395,14 @@ def recreate_with_f_clock(self, f_clock: int) -> "BitTiming":
 
     def __str__(self) -> str:
         segments = [
-            f"BR {self.bitrate} bit/s",
+            f"BR: {self.bitrate:_} bit/s",
             f"SP: {self.sample_point:.2f}%",
             f"BRP: {self.brp}",
             f"TSEG1: {self.tseg1}",
             f"TSEG2: {self.tseg2}",
             f"SJW: {self.sjw}",
             f"BTR: {self.btr0:02X}{self.btr1:02X}h",
-            f"f_clock: {self.f_clock / 1e6:.0f}MHz",
+            f"CLK: {self.f_clock / 1e6:.0f}MHz",
         ]
         return ", ".join(segments)
 
@@ -425,6 +425,9 @@ def __eq__(self, other: object) -> bool:
 
         return self._data == other._data
 
+    def __hash__(self) -> int:
+        return tuple(self._data.values()).__hash__()
+
 
 class BitTimingFd(Mapping):
     """Representation of a bit timing configuration for a CAN FD bus.
@@ -999,19 +1002,19 @@ def recreate_with_f_clock(self, f_clock: int) -> "BitTimingFd":
 
     def __str__(self) -> str:
         segments = [
-            f"NBR: {self.nom_bitrate} bit/s",
+            f"NBR: {self.nom_bitrate:_} bit/s",
             f"NSP: {self.nom_sample_point:.2f}%",
             f"NBRP: {self.nom_brp}",
             f"NTSEG1: {self.nom_tseg1}",
             f"NTSEG2: {self.nom_tseg2}",
             f"NSJW: {self.nom_sjw}",
-            f"DBR: {self.data_bitrate} bit/s",
+            f"DBR: {self.data_bitrate:_} bit/s",
             f"DSP: {self.data_sample_point:.2f}%",
             f"DBRP: {self.data_brp}",
             f"DTSEG1: {self.data_tseg1}",
             f"DTSEG2: {self.data_tseg2}",
             f"DSJW: {self.data_sjw}",
-            f"f_clock: {self.f_clock / 1e6:.0f}MHz",
+            f"CLK: {self.f_clock / 1e6:.0f}MHz",
         ]
         return ", ".join(segments)
 
@@ -1034,6 +1037,9 @@ def __eq__(self, other: object) -> bool:
 
         return self._data == other._data
 
+    def __hash__(self) -> int:
+        return tuple(self._data.values()).__hash__()
+
 
 def _oscillator_tolerance_condition_1(nom_sjw: int, nbt: int) -> float:
     """Arbitration phase - resynchronization"""

doc/bit_timing.rst

@@ -63,10 +63,38 @@ to specify custom bit timings. The :class:`~can.BitTiming` and
 :class:`~can.BitTimingFd` classes can be used for this purpose to specify
 bit timings in a relatively interface agnostic manner.
 
+:class:`~can.BitTiming` or :class:`~can.BitTimingFd` can also help you to
+produce an overview of possible bit timings for your desired bit rate:
+
+    >>> import contextlib
+    >>> import can
+    ...
+    >>> timings = set()
+    >>> for sample_point in range(50, 100):
+    ...     with contextlib.suppress(ValueError):
+    ...         timings.add(
+    ...             can.BitTiming.from_sample_point(
+    ...                 f_clock=8_000_000,
+    ...                 bitrate=250_000,
+    ...                 sample_point=sample_point,
+    ...             )
+    ...         )
+    ...
+    >>> for timing in sorted(timings, key=lambda x: x.sample_point):
+    ...     print(timing)
+    BR: 250_000 bit/s, SP: 50.00%, BRP: 2, TSEG1: 7, TSEG2: 8, SJW: 4, BTR: C176h, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 56.25%, BRP: 2, TSEG1: 8, TSEG2: 7, SJW: 4, BTR: C167h, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 62.50%, BRP: 2, TSEG1: 9, TSEG2: 6, SJW: 4, BTR: C158h, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 68.75%, BRP: 2, TSEG1: 10, TSEG2: 5, SJW: 4, BTR: C149h, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 75.00%, BRP: 2, TSEG1: 11, TSEG2: 4, SJW: 4, BTR: C13Ah, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 81.25%, BRP: 2, TSEG1: 12, TSEG2: 3, SJW: 3, BTR: 812Bh, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 87.50%, BRP: 2, TSEG1: 13, TSEG2: 2, SJW: 2, BTR: 411Ch, CLK: 8MHz
+    BR: 250_000 bit/s, SP: 93.75%, BRP: 2, TSEG1: 14, TSEG2: 1, SJW: 1, BTR: 010Dh, CLK: 8MHz
+
+
 It is possible to specify CAN 2.0 bit timings
 using the config file:
 
-
 .. code-block:: none
 
     [default]

doc/conf.py

@@ -49,6 +49,7 @@
     "sphinx.ext.graphviz",
     "sphinxcontrib.programoutput",
     "sphinx_inline_tabs",
+    "sphinx_copybutton",
 ]
 
 # Now, you can use the alias name as a new role, e.g. :issue:`123`.

doc/doc-requirements.txt

@@ -1,4 +1,5 @@
 sphinx>=5.2.3
 sphinxcontrib-programoutput
 sphinx-inline-tabs
+sphinx-copybutton
 furo

test/test_bit_timing.py

@@ -271,8 +271,8 @@ def test_equality():
 def test_string_representation():
     timing = can.BitTiming(f_clock=8_000_000, brp=1, tseg1=5, tseg2=2, sjw=1)
     assert str(timing) == (
-        "BR 1000000 bit/s, SP: 75.00%, BRP: 1, TSEG1: 5, TSEG2: 2, SJW: 1, "
-        "BTR: 0014h, f_clock: 8MHz"
+        "BR: 1_000_000 bit/s, SP: 75.00%, BRP: 1, TSEG1: 5, TSEG2: 2, SJW: 1, "
+        "BTR: 0014h, CLK: 8MHz"
     )
 
     fd_timing = can.BitTimingFd(
@@ -287,9 +287,9 @@ def test_string_representation():
         data_sjw=10,
     )
     assert str(fd_timing) == (
-        "NBR: 500000 bit/s, NSP: 75.00%, NBRP: 1, NTSEG1: 119, NTSEG2: 40, NSJW: 40, "
-        "DBR: 2000000 bit/s, DSP: 75.00%, DBRP: 1, DTSEG1: 29, DTSEG2: 10, DSJW: 10, "
-        "f_clock: 80MHz"
+        "NBR: 500_000 bit/s, NSP: 75.00%, NBRP: 1, NTSEG1: 119, NTSEG2: 40, NSJW: 40, "
+        "DBR: 2_000_000 bit/s, DSP: 75.00%, DBRP: 1, DTSEG1: 29, DTSEG2: 10, DSJW: 10, "
+        "CLK: 80MHz"
     )
 
 
@@ -316,6 +316,23 @@ def test_repr():
     )
 
 
+def test_hash():
+    _timings = {
+        can.BitTiming(f_clock=8_000_000, brp=1, tseg1=5, tseg2=2, sjw=1, nof_samples=1),
+        can.BitTimingFd(
+            f_clock=80_000_000,
+            nom_brp=1,
+            nom_tseg1=119,
+            nom_tseg2=40,
+            nom_sjw=40,
+            data_brp=1,
+            data_tseg1=29,
+            data_tseg2=10,
+            data_sjw=10,
+        ),
+    }
+
+
 def test_mapping():
     timing = can.BitTiming(f_clock=8_000_000, brp=1, tseg1=5, tseg2=2, sjw=1)
     timing_dict = dict(timing)