Add doctest examples to helperfuncs.py. Also:

* Remove documentation for `check_rtl_assertions` as it should only be used by `Simulation`.
* Rearrange functions in documentation so discouraged functions appear later.
* Make example output wire names more consistent.
* Add more links.

Author: fdxmw

docs/helpers.rst

@@ -39,12 +39,12 @@ Control Flow Hardware
 
 .. autofunction:: pyrtl.corecircuits.mux
 .. autofunction:: pyrtl.corecircuits.select
-.. autofunction:: pyrtl.corecircuits.bitfield_update
-.. autofunction:: pyrtl.corecircuits.bitfield_update_set
 .. autoclass:: pyrtl.helperfuncs.MatchedFields
     :members:
     :undoc-members:
 .. autofunction:: pyrtl.helperfuncs.match_bitpattern
+.. autofunction:: pyrtl.corecircuits.bitfield_update
+.. autofunction:: pyrtl.corecircuits.bitfield_update_set
 
 Interpreting Vectors of Bits
 ----------------------------
@@ -57,11 +57,11 @@ functions below do not create any hardware but rather help in the process of
 reasoning about bit vector representations of human understandable values.
 
 .. autofunction:: pyrtl.helperfuncs.val_to_signed_integer
-.. autofunction:: pyrtl.helperfuncs.val_to_formatted_str
-.. autofunction:: pyrtl.helperfuncs.formatted_str_to_val
 .. autoclass:: pyrtl.helperfuncs.ValueBitwidthTuple
    :members: value, bitwidth
 .. autofunction:: pyrtl.helperfuncs.infer_val_and_bitwidth
+.. autofunction:: pyrtl.helperfuncs.val_to_formatted_str
+.. autofunction:: pyrtl.helperfuncs.formatted_str_to_val
 .. autofunction:: pyrtl.helperfuncs.log2
 
 Debugging
@@ -70,7 +70,6 @@ Debugging
 .. autofunction:: pyrtl.core.set_debug_mode
 .. autofunction:: pyrtl.helperfuncs.probe
 .. autofunction:: pyrtl.helperfuncs.rtl_assert
-.. autofunction:: pyrtl.helperfuncs.check_rtl_assertions
 
 Reductions
 ----------

pyrtl/core.py

@@ -1039,16 +1039,19 @@ def temp_working_block():
     return set_working_block(Block())
 
 
-def set_debug_mode(debug=True):
-    """ Set the global debug mode.
+def set_debug_mode(debug: bool = True):
+    """Set the global debug mode.
 
-    :param bool debug: Optional boolean paramter to which debug mode will be set
+    Sets the debug mode to the specified ``debug`` value. Debug mode is off by default,
+    to improve performance. When debug mode is enabled, all temporary
+    :class:`WireVectors<.WireVector>` will be assigned names based on the line of code
+    on which they were created.
 
-    This function will set the debug mode to the specified value.  Debug mode
-    is, by default, set to off to keep the performance of the system.  With debug
-    mode set to true, all temporary WireVectors created will be given a name based
-    on the line of code on which they were created and a snapshot of the call-stack
-    for those WireVectors will be kept as well.
+    Each :class:`.WireVector` will also save a copy of its call stack when constructed.
+    These call stacks can be inspected as ``WireVector.init_call_stack``, and they will
+    appear in :meth:`Block.sanity_check` error messages.
+
+    :param debug: Optional boolean parameter to which the debug mode will be set.
     """
     global debug_mode
     global _setting_keep_wirevector_call_stack

pyrtl/corecircuits.py

@@ -171,7 +171,7 @@ def concat(*args: WireVectorLike) -> WireVector:
 
     .. note::
 
-        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which help
+        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which helps
         with consistently disassembling, naming, and reassembling fields.
 
     .. doctest only::
@@ -230,7 +230,7 @@ def concat_list(wire_list: list[WireVectorLike]) -> WireVector:
 
     .. note::
 
-        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which help
+        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which helps
         with consistently disassembling, naming, and reassembling fields.
 
     .. doctest only::
@@ -285,15 +285,15 @@ def signed_add(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_add(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_add(neg_three, neg_five)
+        >>> output.bitwidth
         6
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> pyrtl.val_to_signed_integer(sim.inspect("out"), bitwidth=out.bitwidth)
+        >>> pyrtl.val_to_signed_integer(sim.inspect("output"), bitwidth=output.bitwidth)
         -8
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -327,15 +327,15 @@ def signed_sub(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_sub(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_sub(neg_three, neg_five)
+        >>> output.bitwidth
         6
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> pyrtl.val_to_signed_integer(sim.inspect("out"), bitwidth=out.bitwidth)
+        >>> pyrtl.val_to_signed_integer(sim.inspect("output"), bitwidth=output.bitwidth)
         2
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -374,15 +374,15 @@ def signed_mult(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_mult(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_mult(neg_three, neg_five)
+        >>> output.bitwidth
         8
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> pyrtl.val_to_signed_integer(sim.inspect("out"), bitwidth=out.bitwidth)
+        >>> pyrtl.val_to_signed_integer(sim.inspect("output"), bitwidth=output.bitwidth)
         15
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -416,15 +416,15 @@ def signed_lt(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_lt(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_lt(neg_three, neg_five)
+        >>> output.bitwidth
         1
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         0
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -454,15 +454,15 @@ def signed_le(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_le(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_le(neg_three, neg_five)
+        >>> output.bitwidth
         1
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         0
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -493,15 +493,15 @@ def signed_gt(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_gt(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_gt(neg_three, neg_five)
+        >>> output.bitwidth
         1
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         1
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -531,15 +531,15 @@ def signed_ge(a: WireVectorLike, b: WireVectorLike) -> WireVector:
 
         >>> neg_three = pyrtl.Const(val=-3, signed=True, bitwidth=3)
         >>> neg_five = pyrtl.Const(val=-5, signed=True, bitwidth=5)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.signed_ge(neg_three, neg_five)
-        >>> out.bitwidth
+        >>> output <<= pyrtl.signed_ge(neg_three, neg_five)
+        >>> output.bitwidth
         1
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step()
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         1
 
     :param a: A :class:`.WireVector`, or any type that can be coerced to
@@ -580,13 +580,13 @@ def shift_right_arithmetic(bits_to_shift: WireVector,
 
         >>> neg_forty = pyrtl.Const(val=-40, signed=True, bitwidth=7)
         >>> shift_amount = pyrtl.Input(name="shift_amount", bitwidth=3)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.shift_right_arithmetic(neg_forty, shift_amount)
+        >>> output <<= pyrtl.shift_right_arithmetic(neg_forty, shift_amount)
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step(provided_inputs={"shift_amount": 3})
-        >>> pyrtl.val_to_signed_integer(sim.inspect("out"), bitwidth=out.bitwidth)
+        >>> pyrtl.val_to_signed_integer(sim.inspect("output"), bitwidth=output.bitwidth)
         -5
         >>> int(-40 / 2 ** 3)
         -5
@@ -622,13 +622,13 @@ def shift_left_logical(bits_to_shift: WireVector,
 
         >>> three = pyrtl.Const(val=3, bitwidth=6)
         >>> shift_amount = pyrtl.Input(name="shift_amount", bitwidth=3)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.shift_left_logical(three, shift_amount)
+        >>> output <<= pyrtl.shift_left_logical(three, shift_amount)
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step(provided_inputs={"shift_amount": 3})
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         24
         >>> 3 * 2 ** 3
         24
@@ -668,13 +668,13 @@ def shift_right_logical(bits_to_shift: WireVector,
 
         >>> forty = pyrtl.Const(val=40, bitwidth=6)
         >>> shift_amount = pyrtl.Input(name="shift_amount", bitwidth=3)
-        >>> out = pyrtl.Output(name="out")
+        >>> output = pyrtl.Output(name="output")
 
-        >>> out <<= pyrtl.shift_right_logical(forty, shift_amount)
+        >>> output <<= pyrtl.shift_right_logical(forty, shift_amount)
 
         >>> sim = pyrtl.Simulation()
         >>> sim.step(provided_inputs={"shift_amount": 3})
-        >>> sim.inspect("out")
+        >>> sim.inspect("output")
         5
         >>> int(40 / 2 ** 3)
         5
@@ -846,7 +846,7 @@ def bitfield_update(w: WireVectorLike, range_start: int, range_end: int, newvalu
 
     .. note::
 
-        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which help
+        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which helps
         with consistently disassembling, naming, and reassembling fields.
 
     :param w: A :class:`.WireVector`, or any type that can be coerced to
@@ -909,7 +909,7 @@ def bitfield_update_set(w: WireVectorLike,
 
     .. note::
 
-        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which help
+        Consider using :func:`.wire_struct` or :func:`.wire_matrix` instead, which helps
         with consistently disassembling, naming, and reassembling fields.
 
     :param w: A :class:`.WireVector`, or any type that can be coerced to