Refactor docs and README for website (#388)

.github/ISSUE_TEMPLATE/config.yml

@@ -10,5 +10,5 @@ contact_links:
     about: Instant communication... if someone is online.
 
   - name: ROHD Forum
-    url: https://github.com/intel/rohd/wiki/ROHD-Forum
+    url: https://intel.github.io/rohd-website/forum/rohd-forum/
     about: Public periodic meeting for users and developers to discuss topics related to ROHD.

.markdownlint-cli2.jsonc

@@ -2,7 +2,8 @@
   "config": {
     "default": true,
     "MD013": false,
-    "MD041": false
+    "MD041": false,
+    "MD033": false
   },
 
   "ignores": [

CHANGELOG.md

@@ -1,4 +1,8 @@
 
+## Next
+
+- Breaking: Iterable instead of Map in Interface
+
 ## 0.4.2
 
 - Added a GitHub Codespace to the repository as a quick way to experiment with ROHD without any environment setup.

CONTRIBUTING.md

@@ -34,7 +34,7 @@ You can file an issue here: <https://github.com/intel/rohd/issues/new/choose>
 
 ### Meetings in the ROHD Forum
 
-The [ROHD Forum](https://github.com/intel/rohd/wiki/ROHD-Forum) is a periodic virtual meeting for developers and users of ROHD that anyone can join. Feel free to join the call!
+The [ROHD Forum](https://intel.github.io/rohd-website/forum/rohd-forum/) is a periodic virtual meeting for developers and users of ROHD that anyone can join. Feel free to join the call!
 
 ## Getting Started
 

doc/user_guide/_docs/A01-sample-example.md

@@ -10,7 +10,7 @@ Please make sure you had setup your ROHD Framework before running the test. Info
 
 ## A full example of a counter module
 
-To get a quick feel for what ROHD looks like, below is an example of what a simple counter module looks like in ROHD.
+To get a quick feel for what ROHD looks like, below is an example of what a simple counter module looks like in ROHD. Note that this is not the shortest way to describe a simple counter, but expanded to give some examples of different capabilities and be more easily comparable to designs in other languages like SystemVerilog.
 
 ```dart
 // Import the ROHD package

doc/user_guide/_docs/A02-logical_signals.md

@@ -8,7 +8,7 @@ toc: true
 
 ### Logical signals
 
-The fundamental signal building block in ROHD is called [`Logic`]({{ site.baseurl }}api/rohd/Logic-class.html).
+The fundamental signal building block in ROHD is called [`Logic`](https://intel.github.io/rohd/rohd/Logic-class.html).
 
 ```dart
 // a one bit, unnamed signal
@@ -20,9 +20,9 @@ var bus = Logic(name: 'b', width: 8)
 
 #### The value of a signal
 
-You can access the current value of a signal using `value`.  You cannot access this as part of synthesizable ROHD code.  ROHD supports X and Z values and propogation.  If the signal is valid (no X or Z in it), you can also convert it to an int with `valueInt` (ROHD will throw an exception otherwise).  If the signal has more bits than a dart `int` (64 bits, usually), you need to use `valueBigInt` to get a `BigInt` (again, ROHD will throw an exception otherwise).
+You can access the current value of a signal using `value`.  You cannot access this as part of synthesizable ROHD code.  ROHD supports X and Z values and propogation.  If the signal is valid (no X or Z in it), you can also convert it to an `int` with `value.toInt()` (ROHD will throw an exception otherwise).  If the signal has more bits than a dart `int` (64 bits, usually), you need to use `value.toBigInt()` to get a `BigInt` (again, ROHD will throw an exception otherwise).
 
-The value of a `Logic` is of type [`LogicValue`]({{ site.baseurl }}api/rohd/LogicValue-class.html), with pre-defined constant bit values `x`, `z`, `one`, and `zero`.  `LogicValue` has a number of built-in logical operations `(like &, |, ^, +, -, etc.)`.
+The value of a `Logic` is of type [`LogicValue`](https://intel.github.io/rohd/rohd/LogicValue-class.html), with pre-defined constant bit values `x`, `z`, `one`, and `zero`.  `LogicValue` has a number of built-in logical operations (like &, |, ^, +, -, etc.).
 
 ```dart
 var x = Logic(width:2);
@@ -55,8 +55,9 @@ There are three testbench-consumable streams built-in to ROHD `Logic`s: `changed
 Logic mySignal;
 ...
 mySignal.posedge.listen((args) {
-  print("mySignal was ${args.previousValue} before, 
-  but there was a positive edge and the new value is ${args.newValue}");
+  print('mySignal was ${args.previousValue} before,'
+      ' but there was a positive edge and the new value'
+      ' is ${args.newValue}');
 });
 ```
 

doc/user_guide/_docs/A03-constant.md

@@ -1,14 +1,12 @@
 ---
-title: "Constant"
+title: "Constants"
 permalink: /docs/constant/
-excerpt: "Constant"
+excerpt: "Constants"
 last_modified_at: 2022-12-06
 toc: true
 ---
 
-#### Constants
-
-Constants can often be inferred by ROHD automatically, but can also be explicitly defined using [`Const`]({{ site.baseurl }}api/rohd/Const-class.html), which extends `Logic`.
+Constants can often be inferred by ROHD automatically, but can also be explicitly defined using [`Const`](https://intel.github.io/rohd/rohd/Const-class.html), which extends `Logic`.
 
 ```dart
 // a 16 bit constant with value 5

doc/user_guide/_docs/A04-assignment.md

@@ -6,8 +6,6 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Assignment
-
 To assign one signal to the value of another signal, use the `<=` operator.  This is a hardware synthesizable assignment connecting two wires together.
 
 ```dart

doc/user_guide/_docs/A05-logic-math-compare.md

@@ -6,8 +6,6 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Simple logical, mathematical, and comparison operations
-
 Logical operations on signals are very similar to those in SystemVerilog.
 
 ```dart
@@ -18,15 +16,19 @@ a_xor_b   <=  a ^ b;   // xor
 and_a     <=  a.and(); // unary and
 or_a      <=  a.or();  // unary or
 xor_a     <=  a.xor(); // unary xor
+a_pow_b   <=  a.pow(b);// exponent
 a_plus_b  <=  a + b;   // addition
 a_sub_b   <=  a - b;   // subtraction
 a_times_b <=  a * b;   // multiplication
 a_div_b   <=  a / b;   // division
 a_mod_b   <=  a % b;   // modulo
 a_eq_b    <=  a.eq(b)  // equality              NOTE: == is for Object equality of Logic's
+a_neq_b   <=  a.neq(b) // inequality            NOTE: != is for Object inequality of Logic's
 a_lt_b    <=  a.lt(b)  // less than             NOTE: <  is for conditional assignment
 a_lte_b   <=  a.lte(b) // less than or equal    NOTE: <= is for assignment
 a_gt_b    <=  (a > b)  // greater than          NOTE: careful with order of operations, > needs parentheses in this case
+                       // Note: a_gt_b <= a.gt(b) is also supported for greater than.
 a_gte_b   <=  (a >= b) // greater than or equal NOTE: careful with order of operations, >= needs parentheses in this case
+                       // Note: a_gte_b <= a.gte(b) is also supported for greater than or equal.
 answer    <=  mux(selectA, a, b) // answer = selectA ? a : b
 ```

doc/user_guide/_docs/A06-shift-operations.md

@@ -6,9 +6,7 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Shift Operations
-
-Dart has [implemented the triple shift](https://github.com/dart-lang/language/blob/master/accepted/2.14/triple-shift-operator/feature-specification.md) operator ``(>>>)`` in the opposite way as is [implemented in SystemVerilog](https://www.nandland.com/verilog/examples/example-shift-operator-verilog.html).  That is to say in Dart, ``>>>`` means *logical* shift right (fill with 0's), and ``>>`` means *arithmetic* shift right (maintaining sign).  ROHD keeps consistency with Dart's implementation to avoid introducing confusion within Dart code you write (whether ROHD or plain Dart).
+Dart has [implemented the triple shift](https://github.com/dart-lang/language/blob/master/accepted/2.14/triple-shift-operator/feature-specification.md) operator (``>>>``) in the opposite way as is [implemented in SystemVerilog](https://www.nandland.com/verilog/examples/example-shift-operator-verilog.html).  That is to say in Dart, ``>>>`` means *logical* shift right (fill with 0's), and ``>>`` means *arithmetic* shift right (maintaining sign).  ROHD keeps consistency with Dart's implementation to avoid introducing confusion within Dart code you write (whether ROHD or plain Dart).
 
 ```dart
 a << b    // logical shift left

doc/user_guide/_docs/A07-bus-ranges-and-swizzling.md

@@ -6,8 +6,6 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Bus ranges and swizzling
-
 Multi-bit busses can be accessed by single bits and ranges or composed from multiple other signals.  Slicing, swizzling, etc. are also accessible on `LogicValue`s.
 
 ```dart

doc/user_guide/_docs/A08-modules.md

@@ -6,9 +6,7 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Modules
-
-[`Module`]({{ site.baseurl }}api/rohd/Module-class.html)s are similar to modules in SystemVerilog.  They have inputs and outputs and logic that connects them.  There are a handful of rules that *must* be followed when implementing a module.
+[`Module`](https://intel.github.io/rohd/rohd/Module-class.html)s are similar to modules in SystemVerilog.  They have inputs and outputs and logic that connects them.  There are a handful of rules that *must* be followed when implementing a module.
 
 1. All logic within a `Module` must consume only inputs (from the `input` or `addInput` methods) to the Module either directly or indirectly.
 2. Any logic outside of a `Module` must consume the signals only via outputs (from the `output` or `addOutput` methods) of the Module.

doc/user_guide/_docs/A09-sequentials.md

@@ -6,8 +6,6 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Sequentials
-
-ROHD has a basic [`FlipFlop`]({{ site.baseurl }}api/rohd/FlipFlop-class.html) module that can be used as a flip flop.  For more complex sequential logic, use the `Sequential` block described in the Conditionals section.
+ROHD has a basic [`FlipFlop`](https://intel.github.io/rohd/rohd/FlipFlop-class.html) module that can be used as a flip flop.  You can use the shorthand [`flop`](https://intel.github.io/rohd/rohd/flop.html) to construct a `FlipFlop`.  For more complex sequential logic, use the `Sequential` block described in the Conditionals section.
 
 Dart doesn't have a notion of certain signals being "clocks" vs. "not clocks".  You can use any signal as a clock input to sequential logic, and have as many clocks of as many frequencies as you want.

doc/user_guide/_docs/A10-conditionals.md

@@ -6,19 +6,15 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Conditionals
-
-ROHD supports a variety of [`Conditional`]({{ site.baseurl }}api/rohd/Conditional-class.html) type statements that always must fall within a type of `_Always` block, similar to SystemVerilog.  There are two types of `_Always` blocks: [`Sequential`]({{ site.baseurl }}api/rohd/Sequential-class.html) and [`Combinational`]({{ site.baseurl }}api/rohd/Combinational-class.html), which map to SystemVerilog's `always_ff` and `always_comb`, respectively.  `Combinational` takes a list of `Conditional` statements.  Different kinds of `Conditional` statement, such as `If`, may be composed of more `Conditional` statements.  You can create `Conditional` composition chains as deep as you like.
+ROHD supports a variety of [`Conditional`](https://intel.github.io/rohd/rohd/Conditional-class.html) type statements that always must fall within a type of `_Always` block, similar to SystemVerilog.  There are two types of `_Always` blocks: [`Sequential`](https://intel.github.io/rohd/rohd/Sequential-class.html) and [`Combinational`](https://intel.github.io/rohd/rohd/Combinational-class.html), which map to SystemVerilog's `always_ff` and `always_comb`, respectively.  `Combinational` takes a list of `Conditional` statements.  Different kinds of `Conditional` statement, such as `If`, may be composed of more `Conditional` statements.  You can create `Conditional` composition chains as deep as you like.
 
 Conditional statements are executed imperatively and in order, just like the contents of `always` blocks in SystemVerilog.  `_Always` blocks in ROHD map 1-to-1 with SystemVerilog `always` statements when converted.
 
-<!-- markdown-link-check-disable-next-line -->
-Assignments within an `_Always` should be executed conditionally, so use the `<` operator which creates a [`ConditionalAssign`]({{ site.baseurl }}api/rohd/ConditionalAssign-class.html) object instead of `<=`.  The right hand side a `ConditionalAssign` can be anything that can be `put` onto a `Logic`, which includes `int`s.  If you're looking to fill the width of something, use `Const` with the `fill = true`.
+Assignments within an `_Always` should be executed conditionally, so use the `<` operator which creates a [`ConditionalAssign`](https://intel.github.io/rohd/rohd/ConditionalAssign-class.html) object instead of `<=`.  The right hand side a `ConditionalAssign` can be anything that can be `put` onto a `Logic`, which includes `int`s.  If you're looking to fill the width of something, use `Const` with the `fill = true`.
 
 #### `If`
 
-<!-- markdown-link-check-disable-next-line -->
-Below is an example of an [`If`]({{ site.baseurl }}api/rohd/If-class.html) statement in ROHD:
+Below is an example of an [`If`](https://intel.github.io/rohd/rohd/If-class.html) statement in ROHD:
 
 ```dart
 Combinational([
@@ -38,14 +34,13 @@ Combinational([
 ]);
 ```
 
-#### `IfBlock`
+#### `If.block`
 
-<!-- markdown-link-check-disable-next-line -->
-The [`IfBlock`]({{ site.baseurl }}api/rohd/IfBlock-class.html) makes syntax for long chains of if / else if / else chains nicer.  For example:
+The `If.block` constructor makes syntax for long chains of if / else if / else chains nicer.  For example:
 
 ```dart
 Sequential(clk, [
-  IfBlock([
+  If.block([
     // the first one must be Iff (yes, with 2 f's, to differentiate from If above)
     Iff(a & ~b, [
       c < 1,
@@ -66,8 +61,7 @@ Sequential(clk, [
 
 #### `Case` and `CaseZ`
 
-<!-- markdown-link-check-disable-next-line -->
-ROHD supports [`Case`]({{ site.baseurl }}api/rohd/Case-class.html) and [`CaseZ`]({{ site.baseurl }}api/rohd/CaseZ-class.html) statements, including priority and unique flavors, which are implemented in the same way as SystemVerilog.  For example:
+ROHD supports [`Case`](https://intel.github.io/rohd/rohd/Case-class.html) and [`CaseZ`](https://intel.github.io/rohd/rohd/CaseZ-class.html) statements, including priority and unique flavors, which are implemented in the same way as SystemVerilog.  For example:
 
 ```dart
 Combinational([
@@ -84,7 +78,7 @@ Combinational([
       c < 0,
       d < 1,
     ],
-    conditionalType: ConditionalType.Unique
+    conditionalType: ConditionalType.unique
   ),
   CaseZ([b,a].swizzle(),[
       CaseItem(Const(LogicValue.ofString('z1')), [
@@ -93,11 +87,11 @@ Combinational([
     ], defaultItem: [
       e < 0,
     ],
-    conditionalType: ConditionalType.Priority
+    conditionalType: ConditionalType.priority
   )
 ]);
 ```
 
 Note that ROHD supports the 'z' syntax, not the '?' syntax (these are equivalent in SystemVerilog).
 
-There is no support for an equivalent of `casex` from SystemVerilog, since it can easily cause unsynthesizeable code to be generated (see: [https://www.verilogpro.com/verilog-case-casez-casex/](https://www.verilogpro.com/verilog-case-casez-casex/)).
+There is no support for an equivalent of `casex` from SystemVerilog, since it can easily cause unsynthesizeable code to be generated (see: <https://www.verilogpro.com/verilog-case-casez-casex/>).

doc/user_guide/_docs/A11-interfaces.md

@@ -8,20 +8,19 @@ toc: true
 
 Interfaces make it easier to define port connections of a module in a reusable way.  An example of the counter re-implemented using interfaces is shown below.
 
-[`Interface`]({{ site.baseurl }}api/rohd/Interface-class.html) takes a generic parameter for direction type.  This enables you to group signals so make adding them as inputs/outputs easier for different modules sharing this interface.
+[`Interface`](https://intel.github.io/rohd/rohd/Interface-class.html) takes a generic parameter for direction type.  This enables you to group signals so make adding them as inputs/outputs easier for different modules sharing this interface.
 
-The [`Port`]({{ site.baseurl }}api/rohd/Port-class.html) class extends `Logic`, but has a constructor that takes width as a positional argument to make interface port definitions a little cleaner.
+The [`Port`](https://intel.github.io/rohd/rohd/Port-class.html) class extends `Logic`, but has a constructor that takes width as a positional argument to make interface port definitions a little cleaner.
 
 When connecting an `Interface` to a `Module`, you should always create a new instance of the `Interface` so you don't modify the one being passed in through the constructor.  Modifying the same `Interface` as was passed would have negative consequences if multiple `Module`s were consuming the same `Interface`, and also breaks the rules for `Module` input and output connectivity.
 
 The `connectIO` function under the hood calls `addInput` and `addOutput` directly on the `Module` and connects those `Module` ports to the correct ports on the `Interface`s.  Connection is based on signal names.  You can use the `uniquify` Function argument in `connectIO` to uniquify inputs and outputs in case you have multiple instances of the same `Interface` connected to your module.  You can also use the `setPort` function to directly set individual ports on the `Interface` instead of via tagged set of ports.
 
 ```dart
-// Define a set of legal directions for this interface, 
-// and pass as parameter to Interface
+// Define a set of legal directions for this interface, and pass as parameter to Interface
 enum CounterDirection {IN, OUT}
 class CounterInterface extends Interface<CounterDirection> {
-  
+
   // include the getters in the interface so any user can access them
   Logic get en => port('en');
   Logic get reset => port('reset');
@@ -43,23 +42,23 @@ class CounterInterface extends Interface<CounterDirection> {
 }
 
 class Counter extends Module {
-  
+
   late final CounterInterface intf;
   Counter(CounterInterface intf) {
     // define a new interface, and connect it to the interface passed in
     this.intf = CounterInterface(intf.width)
-      ..connectIO(this, intf, 
+      ..connectIO(this, intf,
         // map inputs and outputs to appropriate directions
-        inputTags: {CounterDirection.IN}, 
+        inputTags: {CounterDirection.IN},
         outputTags: {CounterDirection.OUT}
       );
-    
+
     _buildLogic();
   }
 
   void _buildLogic() {
     var nextVal = Logic(name: 'nextVal', width: intf.width);
-    
+
     // access signals directly from the interface
     nextVal <= intf.val + 1;
 

doc/user_guide/_docs/A12-non-synthesizable-signal.md

@@ -1,14 +1,12 @@
 ---
-title: "Non-Synthesizable signal deposition"
+title: "Non-synthesizable signal deposition"
 permalink: /docs/non-synthesizable-signal/
-excerpt: "Non-Synthesizable signal deposition"
+excerpt: "Non-synthesizable signal deposition"
 last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Non-synthesizable signal deposition
-
-For testbench code or other non-synthesizable code, you can use `put` or `inject` on any `Logic` to deposit a value on the signal.  The two functions have similar behavior, but `inject` is shorthand for calling `put` inside of `Simulator.injectAction`, which allows the deposited change to propogate within the same `Simulator` tick.  Generally, you will want to use `inject` for testbench interaction with a design.
+For testbench code or other non-synthesizable code, you can use `put` or `inject` on any `Logic` to deposit a value on the signal.  The two functions have similar behavior, but `inject` is shorthand for calling `put` inside of `Simulator.injectAction`, which allows the deposited change to propogate within the same `Simulator` tick.  Generally, you will want to use `inject` for testbench interaction with a design if it has any sequential elements.
 
 ```dart
 var a = Logic(), b = Logic(width:4);

doc/user_guide/_docs/A13-custom-module-behavior-inline-system-verilog.md

@@ -6,8 +6,6 @@ last_modified_at: 2022-12-06
 toc: true
 ---
 
-### Custom module behavior with custom in-line SystemVerilog representation
-
 Many of the basic built-in gates in Dart implement custom behavior.  An implementation of the NotGate is shown below as an example.  There is different syntax for functions which can be inlined versus those which cannot (the ~ can be inlined).  In this case, the `InlineSystemVerilog` mixin is used, but if it were not inlineable, you could use `CustomSystemVerilog`.  Note that it is mandatory to provide an initial value computation when the module is first created for non-sequential modules.
 
 ```dart