Add a doctest example for rtllib/barrel.py

Author: fdxmw

pyrtl/rtllib/barrel.py

@@ -32,6 +32,28 @@ def barrel_shifter(
 ) -> WireVector:
     """Create a barrel shifter.
 
+    .. doctest only::
+
+        >>> import pyrtl
+        >>> pyrtl.reset_working_block()
+
+    Example::
+
+        >>> bits_to_shift = pyrtl.Input(name="input", bitwidth=8)
+        >>> shift_dist = pyrtl.Input(name="shift_dist", bitwidth=3)
+        >>> output = pyrtl.Output(name="output")
+
+        >>> output <<= pyrtl.rtllib.barrel.barrel_shifter(
+        ...     bits_to_shift,
+        ...     bit_in=1,
+        ...     direction=pyrtl.rtllib.barrel.Direction.RIGHT,
+        ...     shift_dist=shift_dist)
+
+        >>> sim = pyrtl.Simulation()
+        >>> sim.step(provided_inputs={"input": 0x55, "shift_dist": 4})
+        >>> hex(sim.inspect("output"))
+        '0xf5'
+
     :param bits_to_shift: :class:`.WireVector` with the value to shift.
     :param bit_in: A 1-bit :class:`.WireVector` representing the value to shift in.
     :param direction: A one bit :class:`.WireVector` representing the shift direction

tests/rtllib/test_barrel.py

@@ -1,10 +1,20 @@
+import doctest
 import random
 import unittest
 
 import pyrtl
 from pyrtl.rtllib.barrel import Direction, barrel_shifter
 
 
+class TestDocTests(unittest.TestCase):
+    """Test documentation examples."""
+
+    def test_doctests(self):
+        failures, tests = doctest.testmod(m=pyrtl.rtllib.barrel)
+        self.assertGreater(tests, 0)
+        self.assertEqual(failures, 0)
+
+
 class TestBarrel(unittest.TestCase):
     def setUp(self):
         pyrtl.reset_working_block()