Add doctest examples for corecircuits.py. Also:

* Reduce the size of doctest comment blocks.
* Discourage use of `enum_mux`, use conditional assignment instead.
* Update `mux` to use a named `default` parameter, instead of using `**kwargs`.
* Make `shift_left_arithmetic` a proper alias of `shift_left_logical`.
* Add a lot of links.

Author: fdxmw

docs/README.md

@@ -46,8 +46,8 @@ to successfully run the test, but the lines are commented out because they are
 not worth showing in every example. These blocks look like:
 
 ```
-..
-    # For ``doctest``.
+.. doctest only::
+
     >>> import pyrtl
     >>> pyrtl.reset_working_block()
 ```

docs/helpers.rst

@@ -8,7 +8,7 @@ The functions below provide ways of combining, slicing, and extending
 :class:`WireVectors<.WireVector>` in ways that are often useful in hardware
 design.  The functions below extend those member functions of the
 :class:`.WireVector` class itself (which provides support for the Python
-builtin ``len``, slicing e.g. ``wire[3:6]``,
+builtin :func:`len`, slicing e.g. ``wire[3:6]``,
 :meth:`~pyrtl.wire.WireVector.zero_extended`,
 :meth:`~pyrtl.wire.WireVector.sign_extended`, and many operators such as
 addition and multiplication).
@@ -28,8 +28,9 @@ In PyRTL there is only one function in charge of coercing values into
 :class:`WireVectors<.WireVector>`, and that is :func:`.as_wires`. This function
 is called in almost all helper functions and classes to manage the mixture of
 constants and :class:`WireVectors<.WireVector>` that naturally occur in
-hardware development. See :ref:`wirevector_coercion` for examples and more
-details.
+hardware development.
+
+See :ref:`wirevector_coercion` for examples and more details.
 
 .. autofunction:: pyrtl.corecircuits.as_wires
 
@@ -38,7 +39,6 @@ Control Flow Hardware
 
 .. autofunction:: pyrtl.corecircuits.mux
 .. autofunction:: pyrtl.corecircuits.select
-.. autofunction:: pyrtl.corecircuits.enum_mux
 .. autofunction:: pyrtl.corecircuits.bitfield_update
 .. autofunction:: pyrtl.corecircuits.bitfield_update_set
 .. autoclass:: pyrtl.helperfuncs.MatchedFields
@@ -100,10 +100,10 @@ addition, subtraction, multiplication, comparison, and many others).
 .. autofunction:: pyrtl.corecircuits.signed_le
 .. autofunction:: pyrtl.corecircuits.signed_gt
 .. autofunction:: pyrtl.corecircuits.signed_ge
-.. autofunction:: pyrtl.corecircuits.shift_left_arithmetic
-.. autofunction:: pyrtl.corecircuits.shift_right_arithmetic
 .. autofunction:: pyrtl.corecircuits.shift_left_logical
+.. autofunction:: pyrtl.corecircuits.shift_left_arithmetic
 .. autofunction:: pyrtl.corecircuits.shift_right_logical
+.. autofunction:: pyrtl.corecircuits.shift_right_arithmetic
 
 Encoders and Decoders
 ---------------------

pyrtl/core.py

@@ -273,9 +273,9 @@ class Block:
 
       ``ops``: ``&``, ``|``, ``^``, ``n``, ``~``, ``+``, ``-``, ``*``.
 
-      All inputs must be the same ``bitwidth``.  Logical operations produce as many
-      bits as are in the input, while ``+`` and ``-`` produce ``n + 1`` bits, and
-      ``*`` produces ``2 * n`` bits.
+      All inputs must be the same :attr:`~.WireVector.bitwidth`.  Logical operations
+      produce as many bits as are in the input, while ``+`` and ``-`` produce ``n + 1``
+      bits, and ``*`` produces ``2 * n`` bits.
 
     * In addition there are some operations for performing comparisons
       that should perform the operation specified.  The ``=`` ``op`` is checking
@@ -396,8 +396,8 @@ def _add_memblock(self, mem):
     def get_memblock_by_name(self, name: str, strict: bool = False) -> MemBlock:
         """Get a :class:`.MemBlock` from the ``Block``, by name.
 
-        ..
-            # For ``doctest``.
+        .. doctest only::
+
             >>> import pyrtl
             >>> pyrtl.reset_working_block()
 
@@ -446,8 +446,8 @@ def wirevector_subset(self, cls: tuple[type] = None,
 
         Filters ``WireVectors`` by type.
 
-        ..
-            # For ``doctest``.
+        .. doctest only::
+
             >>> import pyrtl
             >>> pyrtl.reset_working_block()
 
@@ -951,7 +951,7 @@ def _get_useful_callpoint_name():
 
     This function walks back the current frame stack attempting to find the
     first frame that is not part of the pyrtl module.  The filename (stripped
-    of path and .py extention) and line number of that call are returned.
+    of path and .py extension) and line number of that call are returned.
     This point should be the point where the user-level code is making the
     call to some pyrtl intrisic (for example, calling "mux").   If the
     attempt to find the callpoint fails for any reason, None is returned.