Bring ToC and Menu into alignment, some minor cleanup within docs (backport #3346)

docs/src/explanations/bundles-and-vecs.md

@@ -102,8 +102,7 @@ ChiselStage.emitSystemVerilog(new MyFlippedModule())
 
 (Chisel 3.2+)
 
-All elements of a `Vec` must be of the same type. If we want to create a Vec where the elements have different types, we
-can use a MixedVec:
+All elements of a `Vec` must have the same parameterization. If we want to create a Vec where the elements have the same type but different parameterizations, we can use a MixedVec:
 
 ```scala mdoc:silent
 import chisel3.util.MixedVec

docs/src/explanations/data-types.md

@@ -24,7 +24,7 @@ collections of values with named fields (similar to ```structs``` in
 other languages), and ```Vecs``` for indexable collections of
 values.
 
-Bundles and Vecs will be covered later.
+Bundles and Vecs will be covered in the next section.
 
 Constant or literal values are expressed using Scala integers or
 strings passed to constructors for the types:

docs/src/explanations/explanations.md

@@ -16,7 +16,6 @@ read these documents in the following order:
 * [Motivation](motivation)
 * [Supported Hardware](supported-hardware)
 * [Data Types](data-types)
-* [DataView](dataview)
 * [Bundles and Vecs](bundles-and-vecs)
 * [Combinational Circuits](combinational-circuits)
 * [Operators](operators)
@@ -29,18 +28,20 @@ read these documents in the following order:
 * [Interfaces and Connections](interfaces-and-connections)
 * [Black Boxes](blackboxes)
 * [Enumerations](chisel-enum)
+* [DataView](dataview)
 * [Functional Module Creation](functional-module-creation)
 * [Muxes and Input Selection](muxes-and-input-selection)
 * [Multiple Clock Domains](multi-clock)
 * [Reset](reset)
-* [Polymorphism and Paramterization](polymorphism-and-parameterization)
+* [Polymorphism and Parameterization](polymorphism-and-parameterization)
 * [Printing in Chisel](printing)
 * [Naming](naming)
 * [Unconnected Wires](unconnected-wires)
-* [Intrinsics](intrinsics)
-* [Annotations](annotations)
-* [Deep Dive into Connection Operators](connection-operators)
 * [Chisel Type vs Scala Type](chisel-type-vs-scala-type)
 * [Connectable Operators](connectable)
 * [Decoders](decoder)
+* [Intrinsic Modules](intrinsics)
+* [Annotations](annotations)
 * [Source Locators](source-locators)
+* [Deep Dive into Legacy Connection Operators](connection-operators)
+

docs/src/explanations/interfaces-and-connections.md

@@ -70,6 +70,7 @@ where Vec takes a size as the first argument and a block returning a port as the
 ## Bulk Connections
 Once we have a defined Interface, we can connect to it via a [`MonoConnect`](https://www.chisel-lang.org/api/latest/chisel3/Data.html#:=) operator (`:=`) or [`BiConnect`](https://www.chisel-lang.org/api/latest/chisel3/Data.html#%3C%3E) operator (`<>`).
 
+
 ### `MonoConnect` Algorithm
 `MonoConnect.connect`, or `:=`, executes a mono-directional connection element-wise.
 
@@ -95,6 +96,8 @@ Note that the RHS element must be readable so, one of these must hold:
 ### `BiConnect` Algorithm
 `BiConnect.connect`, or `<>`, executes a bidirectional connection element-wise. Note that the arguments are left and right (not source and sink) so the intent is for the operation to be commutative. The connect operation will recurse down the left `Data` (with the right `Data`). An exception will be thrown if a movement through the left cannot be matched in the right, or if the right side has extra fields.
 
+> Note: We highly encourage new code to be written with the [`Connectable` Operators](https://www.chisel-lang.org/chisel3/docs/explanations/connectable.html) rather than the `<>` operator.
+
 Using the biconnect `<>` operator, we can now compose two filters into a filter block as follows:
 ```scala mdoc:silent
 class Block extends Module {

docs/src/explanations/operators.md

@@ -56,7 +56,7 @@ native Scala equals operator to remain usable.
 
 The Chisel operator precedence is not directly defined as part of the Chisel language.
 Practically, it is determined by the evaluation order of the circuit,
-which natuarally follows the [Scala operator precedence](https://docs.scala-lang.org/tour/operators.html).
+which naturally follows the [Scala operator precedence](https://docs.scala-lang.org/tour/operators.html).
 If in doubt of operator precedence, use parentheses.
 
 > The Chisel/Scala operator precedence is similar but

docs/src/explanations/width-inference.md

@@ -6,7 +6,7 @@ section: "chisel3"
 
 # Width Inference
 
-Chisel provides bit width inference to reduce design effort. Users are encouraged to manually specify widths of ports and registers to prevent any surprises, but otherwise unspecified widths will be inferred by the Firrtl compiler.
+Chisel provides bit width inference to reduce design effort. Users are encouraged to manually specify widths of ports and registers to prevent any surprises, but otherwise unspecified widths will be inferred by the FIRRTL compiler.
 
 For all circuit components declared with unspecified widths, the FIRRTL compiler will infer the minimum possible width that maintains the legality of all its incoming connections. Implicit here is that inference is done in a right to left fashion in the sense of an assignment statement in chisel, i.e. from the left hand side from the right hand side. If a component has no incoming connections, and the width is unspecified, then an error is thrown to indicate that the width could not be inferred.
 

website/docs/src/main/resources/microsite/data/menu.yml

@@ -48,18 +48,10 @@ options:
         url: chisel3/docs/explanations/supported-hardware.html
         menu_type: chisel3
         menu_section: supported-hardware
-      - title: Connectable
-        url: chisel3/docs/explanations/connectable.html
-        menu_type: chisel3
-        menu_section: connectable
       - title: Data Types
         url: chisel3/docs/explanations/data-types.html
         menu_type: chisel3
         menu_section: data-types
-      - title: Dataview
-        url: chisel3/docs/explanations/dataview.html
-        menu_type: chisel3
-        menu_section: dataview
       - title: Bundles and Vecs
         url: chisel3/docs/explanations/bundles-and-vecs.html
         menu_type: chisel3
@@ -104,14 +96,14 @@ options:
         url: chisel3/docs/explanations/blackboxes.html
         menu_type: chisel3
         menu_section: blackboxes
-      - title: Intrinsics
-        url: chisel3/docs/explanations/intrinsics.html
-        menu_type: chisel3
-        menu_section: intrinsics
       - title: Enumerations
         url: chisel3/docs/explanations/chisel-enum.html
         menu_type: chisel3
         menu_section: enumerations
+      - title: DataView
+        url: chisel3/docs/explanations/dataview.html
+        menu_type: chisel3
+        menu_section: dataview
       - title: Functional Module Creation
         url: chisel3/docs/explanations/functional-module-creation.html
         menu_type: chisel3
@@ -144,30 +136,34 @@ options:
         url: chisel3/docs/explanations/unconnected-wires.html
         menu_type: chisel3
         menu_section: unconnected-wires
-      - title: Intrinsic Modules
-        url: chisel3/docs/explanations/intrinsics.html
-        menu_type: chisel3
-        menu_section: intrinsics
-      - title: Annotations
-        url: chisel3/docs/explanations/annotations.html
-        menu_type: chisel3
-        menu_section: annotations
-      - title: Deep Dive into Connection Operators
-        url: chisel3/docs/explanations/connection-operators.html
-        menu_type: chisel3
-        menu_section: deep-dive-into-connection-operators
       - title: Chisel Type vs Scala Type
         url: chisel3/docs/explanations/chisel-type-vs-scala-type.html
         menu_type: chisel3
         menu_section: chisel-type-vs-scala-type
+      - title: Connectable Operators
+        url: chisel3/docs/explanations/connectable.html
+        menu_type: chisel3
+        menu_section: connectable
       - title: Decoders
         url: chisel3/docs/explanations/decoder.html
         menu_type: chisel3
         menu_section: decoders
+      - title: Intrinsic Modules
+        url: chisel3/docs/explanations/intrinsics.html
+        menu_type: chisel3
+        menu_section: intrinsics
+      - title: Annotations
+        url: chisel3/docs/explanations/annotations.html
+        menu_type: chisel3
+        menu_section: annotations
       - title: Source Locators
         url: chisel3/docs/explanations/source-locators.html
         menu_type: chisel3
         menu_section: source-locators
+      - title: Deep Dive into Connection Operators
+        url: chisel3/docs/explanations/connection-operators.html
+        menu_type: chisel3
+        menu_section: deep-dive-into-connection-operators
   - title: Appendix
     url: chisel3/docs/appendix/appendix.html
     menu_type: chisel3