Improve WireVector documentation:

* Add a new section on `WireVector` coercion.
* Create a `WireVectorLike` type alias for valid inputs to `as_wires`:
  `WireVector | int | bool | str`.
* Add a lot of examples.
* Add more links.
* Start adding some `:raises:` annotations.
* Disable generated documentation for `Input.__init__` and `Output.__init__`.
  Sphinx was using the docstring from the base class, which was confusing.
* Remove unnecessary `:rtype:` annotations. Sphinx retrieves the return type
  from type annotations.
* Update Sphinx dependencies.

Author: fdxmw

docs/basic.rst

@@ -40,15 +40,13 @@ Input Pins
 .. autoclass:: pyrtl.wire.Input
     :members:
     :show-inheritance:
-    :special-members: __init__
 
 Output Pins
 -----------
 
 .. autoclass:: pyrtl.wire.Output
     :members:
     :show-inheritance:
-    :special-members: __init__
 
 Constants
 ---------

docs/helpers.rst

@@ -86,6 +86,8 @@ Reductions
 .. autofunction:: pyrtl.corecircuits.rtl_any
 .. autofunction:: pyrtl.corecircuits.rtl_all
 
+.. _extended_logic_and_arithmetic:
+
 Extended Logic and Arithmetic
 -----------------------------
 

docs/index.rst

@@ -76,16 +76,15 @@ design.
 PyRTL Classes:
 --------------
 
-Perhaps the most important class to understand is :class:`.WireVector`, which
-is the basic type from which you build all hardware.  If you are coming to
-PyRTL from Verilog, a :class:`.WireVector` is closest to a multi-bit `wire`.
-Every new :class:`.WireVector` builds a set of wires which you can then connect
-with other :class:`.WireVector` through overloaded operations such as
-`addition` or `bitwise or`. A bunch of other related classes, including
-:class:`.Input`, :class:`.Output`, :class:`.Const`, and :class:`.Register` are
-all derived from :class:`.WireVector`. Coupled with :class:`.MemBlock` (and
-:class:`.RomBlock`), this is all a user needs to create a functional hardware
-design.
+Perhaps the most important class to understand is :class:`.WireVector`, which is the
+basic type from which you build all hardware. If you are coming to PyRTL from Verilog, a
+:class:`.WireVector` is closest to a multi-bit `wire`. Every new :class:`.WireVector`
+builds a set of wires which you can then connect with other :class:`.WireVector` through
+overloaded operations such as :meth:`~.WireVector.__add__` or
+:meth:`~.WireVector.__or__`. A bunch of other related classes, including
+:class:`.Input`, :class:`.Output`, :class:`.Const`, and :class:`.Register` are all
+derived from :class:`.WireVector`. Coupled with :class:`.MemBlock` (and
+:class:`.RomBlock`), this is all a user needs to create a functional hardware design.
 
 .. inheritance-diagram:: pyrtl.wire.WireVector
                          pyrtl.wire.Input
@@ -134,15 +133,20 @@ which we are implicitly working.  Hardware transforms may make a new
 Errors
 ^^^^^^
 
-Finally, when things go wrong you may hit on one of two ``Exceptions``, neither
-of which is likely recoverable automatically (which is why we limited them to
-only two).  The intention is that ``PyrtlError`` is intended to capture end
-user errors such as invalid constant strings and mis-matched bitwidths.  In
-contrast, ``PyrtlInternalError`` captures internal invariants and assertions
-over the core logic graph which should never be hit when constructing designs
-in the normal ways.  If you hit a confusing ``PyrtlError`` or any
-``PyrtlInternalError`` feel free to file an issue.
+Finally, when things go wrong you may hit an :class:`Exception`, neither of which is
+likely recoverable automatically (which is why we limited them to only two). The
+intention is that :class:`.PyrtlError` is intended to capture end user errors such as
+invalid constant strings and mis-matched bitwidths. In contrast,
+:class:`.PyrtlInternalError` captures internal invariants and assertions over the core
+logic graph which should never be encountered when constructing designs in the normal
+ways. If you hit a confusing :class:`.PyrtlError` or any :class:`.PyrtlInternalError`
+feel free to file an issue.
+
+.. autoclass:: pyrtl.pyrtlexceptions.PyrtlError
+    :members:
 
+.. autoclass:: pyrtl.pyrtlexceptions.PyrtlInternalError
+    :members:
 
 Reference Guide
 ===============

docs/requirements.txt

@@ -67,5 +67,5 @@ sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 typing-extensions==4.14.0
     # via beautifulsoup4
-urllib3==2.4.0
+urllib3==2.5.0
     # via requests

pyrtl/conditional.py

@@ -57,8 +57,9 @@
 
 Every PyRTL wire, register, and memory must have a value in every cycle. PyRTL does not
 support "don't care" or ``X`` values. To satisfy this requirement, conditional
-assignment must assign some value to wires in :data:`conditional_assignment` blocks when
-a value is not specified. This can happen when:
+assignment must always assign a value to every wire in a :data:`conditional_assignment`
+block, even if the :data:`conditional_assignment` does not specify a value. This can
+happen when:
 
 #. A condition is ``True``, but no value is specified for a wire or register in that
    condition's ``with`` block. In the example above, no value is specified for ``r1`` in
@@ -154,8 +155,8 @@ def make_adder(x: pyrtl.WireVector) -> pyrtl.WireVector:
 ``output`` conditional would not make sense, especially if ``output`` is used elsewhere
 in the circuit.
 
-For more :data:`conditional_assignment` examples, see the state machine example in
-``examples/example3-statemachine.py``.
+For more :data:`conditional_assignment` examples, see `the state machine example
+<https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example3-statemachine.py>`_.
 
 """
 # Use the objects "conditional_assignment" and "otherwise" as described above. The
@@ -172,9 +173,10 @@ def make_adder(x: pyrtl.WireVector) -> pyrtl.WireVector:
 #
 
 
-def currently_under_condition():
-    """Returns ``True`` if execution is currently in the context of a
-    :data:`conditional_assignment`.
+def currently_under_condition() -> bool:
+    """
+    :return: ``True`` iff execution is currently in the context of a
+        :data:`conditional_assignment`.
 
     """
     return _depth > 0
@@ -236,8 +238,8 @@ def _reset_conditional_state():
 conditional_assignment = _ConditionalAssignment()
 """Context manager implementing PyRTL's ``conditional_assignment``.
 
-:param dict defaults: Dictionary mapping from WireVector to its default value in this
-    ``conditional_assignment`` block. ``defaults`` are not supported for
+:param dict defaults: Dictionary mapping from :class:`.WireVector` to its default value
+    in this ``conditional_assignment`` block. ``defaults`` are not supported for
     :class:`.MemBlock`.
 
 """

pyrtl/corecircuits.py

@@ -5,7 +5,7 @@
 
 from .pyrtlexceptions import PyrtlError, PyrtlInternalError
 from .core import LogicNet, working_block
-from .wire import Const, WireVector, WrappedWireVector
+from .wire import Const, WireVector, WireVectorLike, WrappedWireVector
 from pyrtl.rtllib import barrel
 from pyrtl.rtllib import muxes
 from .conditional import otherwise
@@ -391,7 +391,7 @@ def match_bitwidth(*args, **opt):
         return (wv.zero_extended(max_len) for wv in args)
 
 
-def as_wires(val, bitwidth=None, truncating=True, block=None):
+def as_wires(val: WireVectorLike, bitwidth=None, truncating=True, block=None):
     """Return wires from `val` which may be wires, integers (including
     IntEnums), strings, or bools.