rtllib documentation cleanup (#491)

* Add AES doctest examples.
* Make AES method names more consistent. Forward calls to the deprecated old
  method names to the new method names.
* Convert PRNG examples to doctest examples.

Also:

* Update PRNGs to use State Registers.
* Include `render_trace` output directly in examples.
* `render_trace`: Remove trailing whitespace from output.
* Always use the `pyrtl.` package prefix in examples.
* Add more documentation links to specific `examples/`.
* Improve documentation for functions with additional software requirements.
* Make the main-page installation instructions consistent with the other `pip install` examples.
* Stop publishing documentation for:
  * half_adder, one_bit_add, ripple_add, ripple_half_add (undocumented)
  * testingutils (nondeterministic tests are generally a bad idea)

Author: fdxmw

docs/basic.rst

@@ -122,9 +122,11 @@ maps from :class:`.WireVector` to its default value for the
 :data:`.conditional_assignment` block. ``defaults`` are not supported for
 :class:`.MemBlock`. See :ref:`conditional_assignment_defaults` for more details.
 
-See `the state machine example
-<https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example3-statemachine.py>`_
-for more examples of :data:`.conditional_assignment`.
+.. note::
+
+   See `example3-statemachine
+   <https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example3-statemachine.py>`_
+   for more :data:`.conditional_assignment` examples.
 
 .. autodata:: pyrtl.otherwise
 

docs/helpers.rst

@@ -23,11 +23,10 @@ many operators such as addition and multiplication).
 Coercion to WireVector
 ----------------------
 
-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.
+:func:`.as_wires` coerces values to :class:`WireVectors<.WireVector>`. Most
+PyRTL helper functions and classes call :func:`.as_wires` on their inputs, 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.
 

docs/index.rst

@@ -23,12 +23,10 @@ Quick links
 Installation
 ============
 
-**Automatic installation**::
+PyRTL is availble in `PyPI <http://pypi.python.org/pypi/pyrtl>`_ and can be
+installed with :program:`pip`::
 
-    pip install pyrtl
-
-PyRTL is listed in `PyPI <http://pypi.python.org/pypi/pyrtl>`_ and can be
-installed with :program:`pip`.
+    $ pip install pyrtl
 
 Design, Simulate, and Inspect in 15 lines
 =========================================

docs/rtllib.rst

@@ -16,6 +16,7 @@ Adders
 .. automodule:: pyrtl.rtllib.adders
    :members:
    :undoc-members:
+   :exclude-members: half_adder, one_bit_add, ripple_add, ripple_half_add
 
 Multipliers
 -----------
@@ -55,10 +56,3 @@ AES-128
 
 .. autoclass:: pyrtl.rtllib.aes.AES
    :members:
-
-Testing Utilities
------------------
-
-.. automodule:: pyrtl.rtllib.testingutils
-   :members:
-   :exclude-members: generate_in_wire_and_values, sim_and_ret_out, sim_and_ret_outws, sim_multicycle, multi_sim_multicycle

docs/screenshots/render_trace.png

@@ -344,6 +344,11 @@ def yosys_area_delay(
     """Synthesize with `Yosys <https://yosyshq.net/yosys/>`_ and return estimate of area
     and delay.
 
+    .. warning::
+
+        ``yosys_area_delay`` requires ``yosys``, which must be `separately installed
+        <https://yosyshq.readthedocs.io/projects/yosys/en/latest/getting_started/installation.html>`_.
+
     If ``leave_in_dir`` is specified, that directory will be used to create any
     temporary files, and the resulting files will be left behind there (which can be
     useful for manual exploration or debugging)

pyrtl/analysis.py

@@ -1182,6 +1182,12 @@ def set_debug_mode(debug: bool = True):
     These call stacks can be inspected as :attr:`WireVector.init_call_stack`, and they
     will appear in :meth:`Block.sanity_check` error messages.
 
+    .. note::
+
+        See `example4-debuggingtools
+        <https://github.com/UCSBarchlab/PyRTL/blob/development/examples/example4-debuggingtools.py>`_
+        for ``debug_mode`` examples.
+
     :param debug: Optional boolean parameter to which the debug mode will be set.
     """
     global debug_mode

pyrtl/core.py

@@ -717,7 +717,7 @@ def match_bitwidth(*args: WireVector, signed: bool = False) -> tuple[WireVector]
         >>> a = pyrtl.Const(-1, name="a_short", signed=True, bitwidth=2)
         >>> b = pyrtl.Const(-3, name="b", signed=True, bitwidth=4)
 
-        >>> a, b = match_bitwidth(a, b, signed=True)
+        >>> a, b = pyrtl.match_bitwidth(a, b, signed=True)
         >>> a.name = "a_long"
         >>> a.bitwidth, b.bitwidth
         (4, 4)
@@ -768,8 +768,8 @@ def as_wires(
     :class:`Const` :class:`WireVector`). See :ref:`wirevector_coercion`. An example::
 
         >>> def make_my_hardware(a, b):
-        ...     a = as_wires(a)
-        ...     b = as_wires(b)
+        ...     a = pyrtl.as_wires(a)
+        ...     b = pyrtl.as_wires(b)
         ...     return (a + b) & 0xf
 
         >>> input = pyrtl.Input(name="input", bitwidth=8)