Reorganize website docs (#1806)

Updates to chisel3 documentation for website:
* guard code examples with mdoc and fix errors encountered along the way
* move some website content here vs splitting the content across two repos
* Bring in the interval-types and loading memories content so that it will be visible from the website
* remove all references to the wiki (deprecated)
* Remove reference to Wiki from the README
* fix tabbing and compile of chisel3-vs-chisel2 section
* Appendix: faqs now guarded and compile
* FAQs: move to resources section

36 files changed, 586 insertions, 262 deletions

diff --git a/docs/README.md b/docs/README.md
index dfc7f934..2a34fc45 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -8,8 +8,7 @@ as part of the PR CI checks,
 forcing the documentation to remain current with the codebase.
 The `src` folder contains the source from which these are generated.
 
-Previous Wiki documentation, now hosted by the website, is contained in the `src/wiki-deprecated` directory.
-We are in the process of converting this documentation into the four categories as described in
+Our documentation is organized into the four categories as described in
 [Divio's documentation system](https://documentation.divio.com/).
 
 The four documentation types are:
@@ -22,9 +21,7 @@ Our documentation strategy for this repository is as follows:
  * Any new public API requires reference documentation.
  * Any new user-facing feature requires explanation documentation.
  * Any bugfixes, corner-cases, or answers to commonly asked questions requires a how-to guide.
- * For now, tutorials are kept in a separate repository. We are working hosting them here.
- * Old documentation is contained in the `src/wiki-deprecated` directory and is being incrementally converted to these
- categories.
+ * Tutorials are kept in a separate repository.
 
 This documentation is hosted on the Chisel [website](https://www.chisel-lang.org).
 
diff --git a/docs/src/appendix/appendix.md b/docs/src/appendix/appendix.md
new file mode 100644
index 00000000..48106fe4
--- /dev/null
+++ b/docs/src/appendix/appendix.md
@@ -0,0 +1,13 @@
+---
+layout: docs
+title:  "Appendix"
+section: "chisel3"
+---
+
+# Appendix
+
+This section covers some less-common Chisel topics.
+
+* [Differences between Chisel3 and Chisel2](chisel3-vs-chisel2)
+* [Experimental Features](experimental-features)
+* [Upgrading from Scala 2.11](upgrading-from-scala-2-11)
diff --git a/docs/src/appendix/chisel3-vs-chisel2.md b/docs/src/appendix/chisel3-vs-chisel2.md
index bfd20348..cafd29e3 100644
--- a/docs/src/appendix/chisel3-vs-chisel2.md
+++ b/docs/src/appendix/chisel3-vs-chisel2.md
@@ -5,6 +5,9 @@ section: "chisel3"
 ---
 
 # Chisel3 vs Chisel2
+```scala mdoc:invisible
+import chisel3._
+```
 
 ## Chisel2 Migration
 For those moving from Chisel2, there were some backwards incompatible changes
@@ -12,55 +15,66 @@ and your RTL needs to be modified to work with Chisel3. The required
 modifications are:
 
  - Wire declaration style:
-   ```scala
-   val wire = UInt(width = 15)
-   ```
+```scala
+  val wire = UInt(width = 15)
+```
    becomes (in Chisel3):
-   ```scala
-   val wire = Wire(UInt(15.W))
-   ```
+```scala mdoc:compile-only
+  val wire = Wire(UInt(15.W))
+```
 
  - I/O declaration style:
-   ```scala
+```scala
    val done = Bool(OUTPUT)
-   ```
+```
    becomes (in Chisel3):
-   ```scala
+```scala mdoc:compile-only
    val wire = Output(Bool())
-   ```
+```
 
  - Sequential memories:
-   ```scala
+```scala mdoc:invisible
+import chisel3._
+val enable = Bool()
+```
+
+```scala
    val addr = Reg(UInt())
    val mem = Mem(UInt(8.W), 1024, seqRead = true)
    val dout = when(enable) { mem(addr) }
-   ```
+```
    becomes (in Chisel3):
-   ```scala
+```scala mdoc:compile-only
    val addr = UInt()
    val mem = SyncReadMem(1024, UInt(8.W))
    val dout = mem.read(addr, enable)
-   ```
+```
 
    Notice the address register is now internal to the SyncReadMem(), but the data
    will still return on the subsequent cycle.
 
- - Generating Verilog with
-   ```scala
+ - Generating Verilog for a module:
+```scala mdoc:invisible
+import chisel3._
+class Hello extends RawModule
+```
+
+```scala
    object Hello {
      def main(args: Array[String]): Unit = {
        chiselMain(Array("--backend", "v"), () => Module(new Hello()))
      }
    }
-   ```
+```
    becomes (in Chisel3):
-   ```scala
+```scala mdoc:compile-only
+   import chisel3.stage.ChiselStage
    object Hello {
      def main(args: Array[String]): Unit = {
-       chisel3.Driver.execute(Array[String](), () => new Hello())
+       (new ChiselStage).emitVerilog(new Hello())
      }
    }
-   ```
+```
 
  - Package changes:
    - Chisel.log2Ceil -> chisel3.util.log2Ceil
@@ -143,14 +157,14 @@ hardware objects), based on specific imports.
 This allows designs to move from less strict front end checks (largely compatible with Chisel2), to stricter checking,
 on a file by file basis, by adjusting specific import statements.
 
-```scala
-    import chisel3.core.ExplicitCompileOptions.Strict
+```scala mdoc:compile-only
+    import chisel3.ExplicitCompileOptions.Strict
 ```
 
 enables stricter connection and usage checks, while
 
-```scala
-    import chisel3.core.ExplicitCompileOptions.NotStrict
+```scala mdoc:compile-only
+    import chisel3.ExplicitCompileOptions.NotStrict
 ```
 
 defers these checks to the `firrtl` compiler.
diff --git a/docs/src/appendix/experimental-features.md b/docs/src/appendix/experimental-features.md
index ba1a028d..0e3f50c8 100644
--- a/docs/src/appendix/experimental-features.md
+++ b/docs/src/appendix/experimental-features.md
@@ -6,12 +6,18 @@ section: "chisel3"
 
 Chisel has a number of new features that are worth checking out.  This page is an informal list of these features and projects.
 
-### FixedPoint
+[FixedPoint](#fixed-point)
+[Module Variants](#module-variants)
+[Module Variants](#bundle-literals)
+[Interval Type](#interval-type)
+[Loading Memories in Simulation](#loading-memories)
+
+### FixedPoint  <a name="fixed-point"></a>
 FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc.  Most common math and logic operations
 are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify
 circuit descriptions. See [FixedPointSpec](https://github.com/freechipsproject/chisel3/tree/master/src/test/scala/chiselTests/FixedPointSpec.scala)
 
-### Module Variants
+### Module Variants <a name="module-variants"></a>
 The standard Chisel *Module* requires a `val io = IO(...)`, the experimental package introduces several
 new ways of defining Modules
 - BaseModule: no contents, instantiable
@@ -21,7 +27,7 @@ new ways of defining Modules
 - RawModule: will be the user-facing version of UserDefinedModule
 - Module: type-aliases to ImplicitModule, the user-facing version of ImplicitModule.
 
-### Bundle Literals
+### Bundle Literals <a name="bundle-literals"></a>
 
 Bundle literals can be constructed via an experimental import:
 
@@ -81,7 +87,7 @@ chisel3.stage.ChiselStage.emitVerilog(new Example3)
 
 Vec literals are not yet supported.
 
-### Interval Type
+### Interval Type <a name="interval-type"></a>
 
 **Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers.
 It augments these types with range information, i.e. upper and lower numeric bounds.
@@ -136,3 +142,57 @@ Consider a Interval with a binary point of 3: aaa.bbb
 | setBinaryPoint(2) | aaa.bb |  2 | X | X  | set the precision |
 | shiftLeftBinaryPoint(2) | a.aabbb |  5 | X | X  | increase the precision |
 | shiftRighBinaryPoint(2) | aaaa.b |  1 | X | X  | reduce the precision |
+
+## Loading Memories in simulation <a name="loading-memories"></a>
+
+Chisel now supports an experimental method for annotating memories to be loaded from a text file containing
+hex or binary numbers. When using verilog simulation it uses the `$readmemh` or `$readmemb`
+verilog extension. The treadle simulator can also load memories using the same annotation.
+
+### How to annotate
+Assuming you have a memory in a Module
+```scala mdoc:invisible
+import chisel3._
+val memoryDepth = 8
+val memoryType = Bool()
+```
+```scala
+val memory = Mem(memoryDepth, memoryType)
+```
+
+At the top of your file just add the import 
+```scala mdoc:silent
+import chisel3.util.experimental.loadMemoryFromFile
+```
+Now just add the memory annotation using
+```scala
+  loadMemoryFromFile(memory, "/workspace/workdir/mem1.txt")
+```
+The default is to use `$readmemh` (which assumes all numbers in the file are in ascii hex),
+bu to use ascii binary there is an optional third argument. You will need to add an additional import.
+```scala mdoc:silent
+import firrtl.annotations.MemoryLoadFileType
+```
+```scala
+  loadMemoryFromFile(memory, "/workspace/workdir/mem1.txt", MemoryLoadFileType.Binary)
+```
+See: [ComplexMemoryLoadingSpec.scala](https://freechipsproject/chisel-testers/src/test/scala/examples/ComplexMemoryLoadingSpec.scala) and
+[LoadMemoryFromFileSpec.scala](https://github.com/freechipsproject/chisel-testers/src/test/scala/examples/LoadMemoryFromFileSpec.scala)
+for working examples.
+
+### Notes on files
+There is no simple answer to where to put this file. It's probably best to create a resource directory somewhere and reference that through a full path. Because these files may be large, we did not want to copy them.
+> Don't forget there is no decimal option, so a 10 in an input file will be 16 decimal
+
+### Aggregate memories
+Aggregate memories are supported but in bit of a clunky way. Since they will be split up into a memory per field, the following convention was adopted.  When specifying the file for such a memory the file name should be regarded as a template. If the memory is a Bundle e.g.
+```scala mdoc:compile-only
+class MemDataType extends Bundle {
+  val a = UInt(16.W)
+  val b = UInt(32.W)
+  val c = Bool()
+}
+```
+The memory will be split into `memory_a`, `memory_b`, and `memory_c`. Similarly if a load file is specified as `"memory-load.txt"` the simulation will expect that there will be three files, `"memory-load_a.txt"`, `"memory-load_b.txt"`, `"memory-load_c.txt"`
+
+> Note: The use of `_` and that the memory field name is added before any file suffix. The suffix is optional but if present is considered to be the text after the last `.` in the file name.
diff --git a/docs/src/wiki-deprecated/cookbook.md b/docs/src/cookbooks/cookbook.md
index 9a10a689..6a8eeebf 100644
--- a/docs/src/wiki-deprecated/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -1,12 +1,13 @@
 ---
 layout: docs
-title:  "Cookbook"
+title:  "General Cookbook"
 section: "chisel3"
 ---
 
-Welcome to the Chisel cookbook. This cookbook is still in early stages. If you have any requests or examples to share, please [file an issue](https://github.com/ucb-bar/chisel3/issues/new) and let us know!
+# General Cookbook
 
-Please note that these examples make use of [Chisel's scala-style printing](printing#scala-style).
+
+Please note that these examples make use of [Chisel's scala-style printing](../explanations/printing#scala-style).
 
 * Converting Chisel Types to/from UInt
   * [How do I create a UInt from an instance of a Bundle?](#how-do-i-create-a-uint-from-an-instance-of-a-bundle)
@@ -368,7 +369,7 @@ However, if we use `@chiselName` then the register previously called `_T` is now
 ```
 ### How do I get Chisel to name the results of vector reads properly?
 Currently, name information is lost when using dynamic indexing. For example:
-```scala
+```scala mdoc:silent
 class Foo extends Module {
   val io = IO(new Bundle {
     val in = Input(Vec(4, Bool()))
diff --git a/docs/src/cookbooks/cookbooks.md b/docs/src/cookbooks/cookbooks.md
new file mode 100644
index 00000000..ee6f5e45
--- /dev/null
+++ b/docs/src/cookbooks/cookbooks.md
@@ -0,0 +1,15 @@
+---
+layout: docs
+title:  "Cookbooks"
+section: "chisel3"
+---
+
+# Cookbooks
+
+Welcome to the Chisel Cookbooks, where we capture frequently-used design patterns or troubleshooting questions.
+If you have any requests or examples to share,
+please [file an issue](https://github.com/chipsalliance/chisel3/issues/new) and let us know!
+
+* [General Cookbooks](cookbook)
+* [Naming Cookbook](naming)
+* [Troubleshooting Guide](troubleshooting)
diff --git a/docs/src/wiki-deprecated/troubleshooting.md b/docs/src/cookbooks/troubleshooting.md
index 333adec4..f8a0cec1 100644
--- a/docs/src/wiki-deprecated/troubleshooting.md
+++ b/docs/src/cookbooks/troubleshooting.md
@@ -3,6 +3,10 @@ layout: docs
 title:  "Troubleshooting"
 section: "chisel3"
 ---
+
+# Troubleshooting
+
+
 This page is a starting point for recording common and not so common problems in developing with Chisel3.  In particular, those situations where there is a work around that will keep you going.
 
 ### `type mismatch` specifying width/value of a `UInt`/`SInt`
@@ -10,7 +14,7 @@ This page is a starting point for recording common and not so common problems in
 *I have some old code that used to work correctly in chisel2 (and still does if I use the `import Chisel._` compatibility layer)
 but causes a `type mismatch` error in straight chisel3:*
 
-```scala
+```scala mdoc:silent:fail
 class TestBlock extends Module {
 	val io = IO(new Bundle {
 		val output = Output(UInt(width=3))
@@ -31,7 +35,9 @@ It was felt these were too prone to error and made it difficult to diagnose erro
 In chisel3, the single argument to the `UInt`/`SInt` object/constructor specifies the *width* and must be a `Width` type.
 Although there are no automatic conversions from `Int` to `Width`, an `Int` may be converted to a `Width` by applying the `W` method to an `Int`.
 In chisel3, the above code becomes:
-```scala
+```scala mdoc:silent
+import chisel3._
+
 class TestBlock extends Module {
 	val io = IO(new Bundle {
 		val output = Output(UInt(3.W))
@@ -40,18 +46,19 @@ class TestBlock extends Module {
 ```
 `UInt`/`SInt` literals may be created from an `Int` with the application of either the `U` or `S` method.
 
-```scala
+```scala mdoc:fail
 UInt(42)
 ```
+
 in chisel2, becomes
-```scala
+```scala mdoc:silent
 42.U
 ```
 in chisel3
 
 A literal with a specific width is created by calling the `U` or `S` method with a `W` argument.
 Use:
-```scala
+```scala mdoc:silent
 1.S(8.W)
 ```
 to create an 8-bit wide (signed) literal with value 1.
diff --git a/docs/src/wiki-deprecated/developers.md b/docs/src/developers/developers.md
index 4c133c54..b2b5dff8 100644
--- a/docs/src/wiki-deprecated/developers.md
+++ b/docs/src/developers/developers.md
@@ -3,9 +3,10 @@ layout: docs
 title:  "Developers"
 section: "chisel3"
 ---
+
 # Developer Documentation
 
-Tips and tricks for Chisel developers.
+Tips and tricks for Chisel developers:
 
 * [Embedding Chisel as an sbt subproject](sbt-subproject)
 * [Test Coverage](test-coverage)
diff --git a/docs/src/wiki-deprecated/sbt-subproject.md b/docs/src/developers/sbt-subproject.md
index 77273800..44d2916b 100644
--- a/docs/src/wiki-deprecated/sbt-subproject.md
+++ b/docs/src/developers/sbt-subproject.md
@@ -4,7 +4,7 @@ title:  "Developers"
 section: "chisel3"
 ---
 
-## Chisel as an sbt subproject
+# Chisel as an sbt subproject
 
 In order to use the constructs defined in the Chisel3 library, those definitions must be made available to the Scala
 compiler at the time a project dependent on them is compiled.
diff --git a/docs/src/wiki-deprecated/style.md b/docs/src/developers/style.md
index c845f7b4..80e1e083 100644
--- a/docs/src/wiki-deprecated/style.md
+++ b/docs/src/developers/style.md
@@ -1,10 +1,22 @@
-# Chisel Style Guide
+---
+layout: docs
+title:  "Style Guide"
+section: "chisel3"
+---
+
+# Chisel Developers Style Guide
+
+This document describes the syle used within the `chisel3`
+and related projects (`firrtl`, `treadle`, etc). It does not
+capture requirements for code which is written using these libraries,
+although projects may choose to adopt these guidelines.
 
 The Chisel style guide reflects the [Google Java style
 guide](http://google.github.io/styleguide/javaguide.html) and the [General Public Scala style
-guide](http://docs.scala-lang.org/style/). Specific rules below are to clarify
+guide](http://docs.scala-lang.org/style/). The specific rules below are to clarify
 the style used for the chisel3 repo and repos related to Chisel (Firrtl).
 
+
 **Goal:** Readability and consistency are the main purposes of the style guide.
 Writing your code so someone else (or yourself) can grok it later is important
 to code health and quality.
@@ -134,8 +146,14 @@ val queueOut = Queue(
 ## Naming Conventions
 
 Chisel follows the [Scala Naming Conventions](http://docs.scala-lang.org/style/naming-conventions.html).
-In general, Chisel code should use CamelCase for naming (ie. the first letter
-of each word is capitalized except sometimes the first word).
+In general, Chisel code should use `lowerCamelCase` for variable naming (ie. the first letter
+of each word is capitalized except for the first word) and `UpperCamelCase` for class names.
+
+> Using these guidelines can result in verilog which is noncompliant with common verilog coding standards, e.g.
+the [lowRISC verilog coding style](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md#naming).
+Authors of Chisel code that translates to hardware constructs might therefore prefer to use `snake_case`. However,
+generated code can always be transformed to meet various emitted code requirements, so the official Chisel style
+guide follows the Scala convention.
 
 ### Why CamelCase instead of Snake\_Case?
 
diff --git a/docs/src/wiki-deprecated/test-coverage.md b/docs/src/developers/test-coverage.md
index a3a622a2..099db4bb 100644
--- a/docs/src/wiki-deprecated/test-coverage.md
+++ b/docs/src/developers/test-coverage.md
@@ -4,6 +4,8 @@ title:  "Test Coverage"
 section: "chisel3"
 ---
 
+# Test Coverage
+
 ## Test Coverage Setup
 
 Chisel's sbt build instructions contain the requisite plug-in (sbt-scoverage) for generating test coverage information. Please see the [sbt-scoverage web page](https://github.com/scoverage/sbt-scoverage) for details on the plug-in.
diff --git a/docs/src/explanations/annotations.md b/docs/src/explanations/annotations.md
index 19d24605..510ebca5 100644
--- a/docs/src/explanations/annotations.md
+++ b/docs/src/explanations/annotations.md
@@ -4,6 +4,8 @@ title:  "Annotations"
 section: "chisel3"
 ---
 
+# Annotations
+
 `Annotation`s are metadata containers associated with zero or more "things" in a FIRRTL circuit.
 Commonly, `Annotation`s are used to communicate information from Chisel to a specific, custom FIRRTL `Transform`.
 In this way `Annotation`s can be viewed as the "arguments" that a specific `Transform` consumes.
@@ -132,10 +134,8 @@ class ModC(widthC: Int) extends Module {
 
 Compiling this circuit to Verilog will then result in the `InfoTransform` running and the added `println`s showing information about the components annotated.
 
-```scala mdoc
+```scala mdoc:compile-only
 import chisel3.stage.{ChiselStage, ChiselGeneratorAnnotation}
 
-// This currently doesn't work because of mdoc limitations. However, it will work
-// in your normal Scala code.
-//(new ChiselStage).execute(Array.empty, Seq(ChiselGeneratorAnnotation(() => new ModC(4))))
+(new ChiselStage).execute(Array.empty, Seq(ChiselGeneratorAnnotation(() => new ModC(4))))
 ```
diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md
index bac9393a..78626c42 100644
--- a/docs/src/explanations/bundles-and-vecs.md
+++ b/docs/src/explanations/bundles-and-vecs.md
@@ -64,7 +64,7 @@ Note that the builtin Chisel primitive and aggregate classes do not
 require the `new` when creating an instance, whereas new user
 datatypes will.  A Scala `apply` constructor can be defined so
 that a user datatype also does not require `new`, as described in
-[Function Constructor](../wiki-deprecated/functional-module-creation).
+[Function Constructor](../explanations/functional-module-creation).
 
 ### Flipping Bundles
 
diff --git a/docs/src/wiki-deprecated/combinational-circuits.md b/docs/src/explanations/combinational-circuits.md
index 813549c9..b9e5b8c6 100644
--- a/docs/src/wiki-deprecated/combinational-circuits.md
+++ b/docs/src/explanations/combinational-circuits.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Combinational Circuits"
 section: "chisel3"
 ---
+
+# Combinational Circuits
+
 A circuit is represented as a graph of nodes in Chisel.  Each node is
 a hardware operator that has zero or more inputs and that drives one
 output.  A literal, introduced above, is a degenerate kind of node
diff --git a/docs/src/wiki-deprecated/data-types.md b/docs/src/explanations/data-types.md
index e931247f..6ac6077b 100644
--- a/docs/src/wiki-deprecated/data-types.md
+++ b/docs/src/explanations/data-types.md
@@ -4,6 +4,8 @@ title:  "Data Types"
 section: "chisel3"
 ---
 
+# Chisel Data Types
+
 Chisel datatypes are used to specify the type of values held in state
 elements or flowing on wires.  While hardware designs ultimately
 operate on vectors of binary digits, other more abstract
@@ -17,7 +19,7 @@ format.  Boolean values are represented as type ```Bool```.  Note
 that these types are distinct from Scala's builtin types such as
 ```Int``` or ```Boolean```.
 
-> There is a new experimental type **Interval** which gives the developer more control of the type by allowing the definition of an IntervalRange.  See: [Interval Type](interval-type)
+> There is a new experimental type **Interval** which gives the developer more control of the type by allowing the definition of an IntervalRange.  See: [Interval Type](../appendix/experimental-features#interval-type)
 
 Additionally, Chisel defines `Bundles` for making
 collections of values with named fields (similar to ```structs``` in
diff --git a/docs/src/explanations/explanations.md b/docs/src/explanations/explanations.md
new file mode 100644
index 00000000..01894ad7
--- /dev/null
+++ b/docs/src/explanations/explanations.md
@@ -0,0 +1,39 @@
+---
+layout: docs
+title:  "Explanations"
+section: "chisel3"
+---
+
+# Explanations
+
+Explanation documentation gives background and context.
+They can also explain why things are so - design decisions,
+historical reasons, technical constraints.
+
+If you are just getting started with Chisel, we suggest you
+read these documents in the following order:
+
+* [Motivation](motivation)
+* [Supported Hardware](supported-hardware)
+* [Data Types](data-types)
+* [Bundles and Vecs](bundles-and-vecs)
+* [Combinational Circuits](combinational-circuits)
+* [Operators](operators)
+* [Width Inference](width-inference)
+* [Functional Abstraction](functional-abstraction)
+* [Ports](ports)
+* [Modules](modules)
+* [Sequential Circuits](sequential-circuits)
+* [Memories](memories)
+* [Interfaces and Connections](interfaces-and-connections)
+* [Black Boxes](blackboxes)
+* [Enumerations](enumerations)
+* [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)
+* [Printing in Chisel](printing)
+* [Naming](naming)
+* [Unconnected Wires](unconnected-wires)
+* [Annotations](annotations)
diff --git a/docs/src/wiki-deprecated/functional-abstraction.md b/docs/src/explanations/functional-abstraction.md
index 04dde7d1..4e3900b6 100644
--- a/docs/src/wiki-deprecated/functional-abstraction.md
+++ b/docs/src/explanations/functional-abstraction.md
@@ -3,11 +3,19 @@ layout: docs
 title:  "Functional Abstraction"
 section: "chisel3"
 ---
+
+# Functional Abstraction
+
 We can define functions to factor out a repeated piece of logic that
 we later reuse multiple times in a design.  For example, we can wrap
 up our earlier example of a simple combinational logic block as
 follows:
-```scala
+
+```scala mdoc:invisible
+import chisel3._
+```
+
+```scala mdoc:silent
 def clb(a: UInt, b: UInt, c: UInt, d: UInt): UInt =
   (a & b) | (~c & d)
 ```
@@ -21,9 +29,6 @@ argument list.  The equals (```=})```sign separates the function argument list f
 definition.
 
 We can then use the block in another circuit as follows:
-```scala
+```scala mdoc:silent
 val out = clb(a,b,c,d)
 ```
-
-We will later describe many powerful ways to use functions to
-construct hardware using Scala's functional programming support.
diff --git a/docs/src/wiki-deprecated/functional-module-creation.md b/docs/src/explanations/functional-module-creation.md
index 3e2e95bc..407edb1d 100644
--- a/docs/src/wiki-deprecated/functional-module-creation.md
+++ b/docs/src/explanations/functional-module-creation.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Functional Module Creation"
 section: "chisel3"
 ---
+
+# Functional Module Creation
+
 Objects in Scala have a pre-existing creation function (method) called `apply`.
 When an object is used as value in an expression (which basically means that the constructor was called), this method determines the returned value.
 When dealing with hardware modules, one would expect the module output to be representative of the hardware module's functionality.
@@ -12,7 +15,19 @@ This can be referred to as creating a functional interface for module constructi
 If we apply this on the standard mux2 example, we would to return the mux2 output ports when we used mux2 in an expression.
 Implementing this requires building a constructor that takes multiplexer inputs as parameters and returns the multiplexer output:
 
-```scala
+```scala mdoc:silent
+import chisel3._
+
+class Mux2 extends Module {
+  val io = IO(new Bundle {
+    val sel = Input(Bool())
+    val in0 = Input(UInt())
+    val in1 = Input(UInt())
+    val out = Output(UInt())
+  })
+  io.out := Mux(io.sel, io.in0, io.in1)
+}
+
 object Mux2 {
   def apply(sel: UInt, in0: UInt, in1: UInt) = {
     val m = Module(new Mux2)
@@ -28,7 +43,7 @@ As we can see in the code example, we defined the `apply` method to take the Mux
 By defining modules in this way, it is easier to later implement larger and more complex version of this regular module.
 For example, we previously implemented Mux4 like this:
 
-```scala
+```scala mdoc:silent
 class Mux4 extends Module {
   val io = IO(new Bundle {
     val in0 = Input(UInt(1.W))
@@ -60,7 +75,33 @@ class Mux4 extends Module {
 However, by using the creation function we redefined for Mux2, we can now use the Mux2 outputs as values of the modules themselves
 when writing the Mux4 output expression:
 
-```scala
+```scala mdoc:invisible:reset
+// We need to re-do this to allow us to `reset`
+// and then re-define Mux4
+import chisel3._
+
+class Mux2 extends Module {
+  val io = IO(new Bundle {
+    val sel = Input(Bool())
+    val in0 = Input(UInt())
+    val in1 = Input(UInt())
+    val out = Output(UInt())
+  })
+  io.out := Mux(io.sel, io.in0, io.in1)
+}
+
+object Mux2 {
+  def apply(sel: UInt, in0: UInt, in1: UInt) = {
+    val m = Module(new Mux2)
+    m.io.in0 := in0
+    m.io.in1 := in1
+    m.io.sel := sel
+    m.io.out
+  }
+}
+```
+
+```scala mdoc:silent
 class Mux4 extends Module {
   val io = IO(new Bundle {
     val in0 = Input(UInt(1.W))
@@ -76,4 +117,4 @@ class Mux4 extends Module {
 }
 ```
 
-This allows to write more intuitively readable hardware connection descriptions, which are similar to software expression evaluation.
+This allows us to write more intuitively readable hardware connection descriptions, which are similar to software expression evaluation.
diff --git a/docs/src/wiki-deprecated/interfaces-and-connections.md b/docs/src/explanations/interfaces-and-connections.md
index 5902f5cd..9f48b642 100644
--- a/docs/src/wiki-deprecated/interfaces-and-connections.md
+++ b/docs/src/explanations/interfaces-and-connections.md
@@ -3,6 +3,7 @@ layout: docs
 title:  "Interfaces and Connections"
 section: "chisel3"
 ---
+
 # Interfaces & Bulk Connections
 
 For more sophisticated modules it is often useful to define and instantiate interface classes while defining the IO for a module. First and foremost, interface classes promote reuse allowing users to capture once and for all common interfaces in a useful form.
@@ -15,7 +16,11 @@ Note that Chisel has some built-in standard interface which should be used whene
 
 As we saw earlier, users can define their own interfaces by defining a class that subclasses Bundle. For example, a user could define a simple link for hand-shaking data as follows:
 
-```scala
+```scala mdoc:invisible
+import chisel3._
+```
+
+```scala mdoc:silent
 class SimpleLink extends Bundle {
   val data = Output(UInt(16.W))
   val valid = Output(Bool())
@@ -23,7 +28,7 @@ class SimpleLink extends Bundle {
 ```
 
 We can then extend SimpleLink by adding parity bits using bundle inheritance:
-```scala
+```scala mdoc:silent
 class PLink extends SimpleLink {
   val parity = Output(UInt(5.W))
 }
@@ -31,7 +36,7 @@ class PLink extends SimpleLink {
 In general, users can organize their interfaces into hierarchies using inheritance.
 
 From there we can define a filter interface by nesting two PLinks into a new FilterIO bundle:
-```scala
+```scala mdoc:silent
 class FilterIO extends Bundle {
   val x = Flipped(new PLink)
   val y = new PLink
@@ -40,10 +45,10 @@ class FilterIO extends Bundle {
 where flip recursively changes the direction of a bundle, changing input to output and output to input.
 
 We can now define a filter by defining a filter class extending module:
-```scala
+```scala mdoc:silent
 class Filter extends Module {
   val io = IO(new FilterIO)
-  ...
+  // ...
 }
 ```
 where the io field contains FilterIO.
@@ -51,7 +56,7 @@ where the io field contains FilterIO.
 ## Bundle Vectors
 
 Beyond single elements, vectors of elements form richer hierarchical interfaces. For example, in order to create a crossbar with a vector of inputs, producing a vector of outputs, and selected by a UInt input, we utilize the Vec constructor:
-```scala
+```scala mdoc:silent
 import chisel3.util.log2Ceil
 class CrossbarIo(n: Int) extends Bundle {
   val in = Vec(n, Flipped(new PLink))
@@ -64,7 +69,7 @@ where Vec takes a size as the first argument and a block returning a port as the
 ## Bulk Connections
 
 We can now compose two filters into a filter block as follows:
-```scala
+```scala mdoc:silent
 class Block extends Module {
   val io = IO(new FilterIO)
   val f1 = Module(new Filter)
@@ -96,7 +101,7 @@ Usually, we use the utility function [`Decoupled()`](https://chisel.eecs.berkele
 
 Take a look at the following example Chisel code to better understand exactly what is generated:
 
-```scala
+```scala mdoc:silent:reset
 import chisel3._
 import chisel3.util.Decoupled
 
diff --git a/docs/src/wiki-deprecated/memories.md b/docs/src/explanations/memories.md
index e4b9a80b..792d176e 100644
--- a/docs/src/wiki-deprecated/memories.md
+++ b/docs/src/explanations/memories.md
@@ -3,27 +3,32 @@ layout: docs
 title:  "Memories"
 section: "chisel3"
 ---
+
+# Memories
+
 Chisel provides facilities for creating both read only and read/write memories.
 
 ## ROM
 
 Users can define read only memories with a `Vec`:
-
-``` scala
+```scala mdoc:invisible
+import chisel3._
+```
+``` scala mdoc:compile-only
     VecInit(inits: Seq[T])
     VecInit(elt0: T, elts: T*)
 ```
 
 where `inits` is a sequence of initial `Data` literals that initialize the ROM. For example,  users cancreate a small ROM initialized to 1, 2, 4, 8 and loop through all values using a counter as an address generator as follows:
 
-``` scala
+``` scala mdoc:compile-only
     val m = VecInit(Array(1.U, 2.U, 4.U, 8.U))
     val r = m(counter(m.length.U))
 ```
 
 We can create an *n* value sine lookup table using a ROM initialized as follows:
 
-``` scala
+``` scala mdoc:silent
     def sinTable(amp: Double, n: Int) = {
       val times =
         (0 until n).map(i => (i*2*Pi)/(n.toDouble-1) - Pi)
@@ -37,7 +42,7 @@ We can create an *n* value sine lookup table using a ROM initialized as follows:
 
 where `amp` is used to scale the fixpoint values stored in the ROM.
 
-## Memories
+## Read-Write Memories
 
 Memories are given special treatment in Chisel since hardware implementations of memory vary greatly. For example, FPGA memories are instantiated quite differently from ASIC memories. Chisel defines a memory abstraction that can map to either simple Verilog behavioural descriptions or to instances of memory modules that are available from external memory generators provided by foundry or IP vendors.
 
@@ -168,3 +173,4 @@ class MaskedRWSmem extends Module {
   }
 }
 ```
+
diff --git a/docs/src/wiki-deprecated/modules.md b/docs/src/explanations/modules.md
index 23006c9c..32cbff2e 100644
--- a/docs/src/wiki-deprecated/modules.md
+++ b/docs/src/explanations/modules.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Modules"
 section: "chisel3"
 ---
+
+# Modules
+
 Chisel *modules* are very similar to Verilog *modules* in
 defining a hierarchical structure in the generated circuit.
 
diff --git a/docs/src/wiki-deprecated/introduction.md b/docs/src/explanations/motivation.md
index 43fc9887..afe02a7b 100644
--- a/docs/src/wiki-deprecated/introduction.md
+++ b/docs/src/explanations/motivation.md
@@ -1,32 +1,12 @@
 ---
 layout: docs
-title:  "Introduction"
+title:  "Motivation"
 section: "chisel3"
 ---
-This document is a tutorial introduction to _Chisel_ (Constructing
-Hardware In a Scala Embedded Language).  Chisel is a hardware
-construction language embedded in the high-level programming language
-Scala.  At some point we will provide a proper reference manual, in
-addition to more tutorial examples.  In the meantime, this document
-along with a lot of trial and error should set you on your way to
-using Chisel. _Chisel is really only a set of special class
-definitions, predefined objects, and usage conventions within Scala,
-so when you write Chisel you are actually writing a Scala
-program that constructs a hardware graph._  However, for the tutorial we don't presume that you
-understand how to program in Scala.  We will point out necessary Scala
-features through the Chisel examples we give, and significant hardware
-designs can be completed using only the material contained herein.
-But as you gain experience and want to make your code simpler or more
-reusable, you will find it important to leverage the underlying power
-of the Scala language. We recommend you consult one of the excellent
-Scala books to become more expert in Scala programming.
 
->Through the tutorial, we format commentary on our design choices as in
-this paragraph.  You should be able to skip the commentary sections
-and still fully understand how to use Chisel, but we hope you'll find
-them interesting.
+# Motivation -- "Why Chisel?"
 
->We were motivated to develop a new hardware language by years of
+We were motivated to develop a new hardware language by years of
 struggle with existing hardware description languages in our research
 projects and hardware design courses.  _Verilog_ and _VHDL_ were developed
 as hardware _simulation_ languages, and only later did they become
@@ -39,7 +19,7 @@ While it is possible to use a subset of these languages and still get
 acceptable results, they nonetheless present a cluttered and confusing
 specification model, particularly in an instructional setting.
 
->However, our strongest motivation for developing a new hardware
+However, our strongest motivation for developing a new hardware
 language is our desire to change the way that electronic system design
 takes place.  We believe that it is important to not only teach
 students how to design circuits, but also to teach them how to design
@@ -56,7 +36,7 @@ circuit generation, they lack the powerful facilities present in
 modern programming languages, such as object-oriented programming,
 type inference, support for functional programming, and reflection.
 
->Instead of building a new hardware design language from scratch, we
+Instead of building a new hardware design language from scratch, we
 chose to embed hardware construction primitives within an existing
 language.  We picked Scala not only because it includes the
 programming features we feel are important for building circuit
diff --git a/docs/src/wiki-deprecated/muxes-and-input-selection.md b/docs/src/explanations/muxes-and-input-selection.md
index fd7b7e7f..ae087e83 100644
--- a/docs/src/wiki-deprecated/muxes-and-input-selection.md
+++ b/docs/src/explanations/muxes-and-input-selection.md
@@ -3,19 +3,24 @@ layout: docs
 title:  "Muxes and Input Selection"
 section: "chisel3"
 ---
+
+# Muxes and Input Selection
+
 Selecting inputs is very useful in hardware description, and therefore Chisel provides several built-in generic input-selection implementations.
+
 ### Mux
 The first one is `Mux`. This is a 2-input selector. Unlike the `Mux2` example which was presented previously, the built-in `Mux` allows
 the inputs (`in0` and `in1`) to be any datatype as long as they are the same subclass of `Data`.
 
-by using the functional module creation feature presented in the previous section, we can create multi-input selector in a simple way:
+By using the functional module creation feature presented in the previous section, we can create multi-input selector in a simple way:
 
 ```scala
 Mux(c1, a, Mux(c2, b, Mux(..., default)))
 ```
 
 ### MuxCase
-However, this is not necessary since Chisel also provides the built-in `MuxCase`, which implements that exact feature.
+
+The nested `Mux` is not necessary since Chisel also provides the built-in `MuxCase`, which implements that exact feature.
 `MuxCase` is an n-way `Mux`, which can be used as follows:
 
 ```scala
@@ -44,13 +49,14 @@ MuxCase(default,
 Note that the conditions/cases/selectors (eg. c1, c2) must be in parentheses.
 
 ### Mux1H
-Another ```Mux``` utility is ```Mux1H``` that takes a sequence of selectors and values and returns the value associated with the one selector that is set. If zero or multiple selectors are set the behavior is undefined.  For example:
+Another ```Mux``` utility is the one-hot mux, ```Mux1H```. It takes a sequence of selectors and values and returns the value associated with the one selector that is set. If zero or multiple selectors are set the behavior is undefined.  For example:
+
 ```scala
-  val hotValue = chisel3.util.oneHotMux(Seq(
+  val hotValue = chisel3.util.Mux1H(Seq(
     io.selector(0) -> 2.U,
     io.selector(1) -> 4.U,
     io.selector(2) -> 8.U,
     io.selector(4) -> 11.U,
   ))
 ```
-```oneHotMux``` whenever possible generates *Firrtl* that is readily optimizable as low depth and/or tree.  This optimization is not possible when the values are of type ```FixedPoint``` or an aggregate type that contains ```FixedPoint```s and results instead as a simple ```Mux``` tree.  This behavior could be sub-optimal.  As ```FixedPoint``` is still *experimental* this behavior may change in the future.
+```Mux1H``` whenever possible generates *Firrtl* that is readily optimizable as low depth and/or tree.  This optimization is not possible when the values are of type ```FixedPoint``` or an aggregate type that contains ```FixedPoint```s and results instead as a simple ```Mux``` tree.  This behavior could be sub-optimal.  As ```FixedPoint``` is still *experimental* this behavior may change in the future.
diff --git a/docs/src/wiki-deprecated/operators.md b/docs/src/explanations/operators.md
index c23e2009..231a53fa 100644
--- a/docs/src/wiki-deprecated/operators.md
+++ b/docs/src/explanations/operators.md
@@ -3,7 +3,9 @@ layout: docs
 title:  "Operators"
 section: "chisel3"
 ---
-### List of operators
+
+# Chisel Operators
+
 Chisel defines a set of hardware operators:
 
 | Operation        | Explanation |
diff --git a/docs/src/wiki-deprecated/polymorphism-and-parameterization.md b/docs/src/explanations/polymorphism-and-parameterization.md
index c652baca..94b896b1 100644
--- a/docs/src/wiki-deprecated/polymorphism-and-parameterization.md
+++ b/docs/src/explanations/polymorphism-and-parameterization.md
@@ -3,12 +3,15 @@ layout: docs
 title:  "Polymorphism and Parameterization"
 section: "chisel3"
 ---
+
+# Polymorphism and Paramterization
+
 _This section is advanced and can be skipped at first reading._
 
 Scala is a strongly typed language and uses parameterized types to specify generic functions and classes.
 In this section, we show how Chisel users can define their own reusable functions and classes using parameterized classes.
 
-# Parameterized Functions
+## Parameterized Functions
 
 Earlier we defined `Mux2` on `Bool`, but now we show how we can define a generic multiplexer function.
 We define this function as taking a boolean condition and con and alt arguments (corresponding to then and else expressions) of type `T`:
@@ -59,13 +62,15 @@ In this case, `reduce` creates a summation circuit.
 Finally, the `FIR` function is constrained to work on inputs of type `Num` where Chisel multiplication and addition are defined.
 --->
 
-# Parameterized Classes
+## Parameterized Classes
 
 Like parameterized functions, we can also parameterize classes to make them more reusable.
 For instance, we can generalize the Filter class to use any kind of link.
 We do so by parameterizing the `FilterIO` class and defining the constructor to take a single argument `gen` of type `T` as below.
-
-```scala
+```scala mdoc:invisible
+import chisel3._
+```
+```scala mdoc:silent
 class FilterIO[T <: Data](gen: T) extends Bundle {
   val x = Input(gen)
   val y = Output(gen)
@@ -74,22 +79,32 @@ class FilterIO[T <: Data](gen: T) extends Bundle {
 
 We can now define `Filter` by defining a module class that also takes a link type constructor argument and passes it through to the `FilterIO` interface constructor:
 
-```scala
+```scala mdoc:silent
 class Filter[T <: Data](gen: T) extends Module {
   val io = IO(new FilterIO(gen))
-  ...
+  // ...
 }
 ```
 
 We can now define a `PLink`-based `Filter` as follows:
-
-```scala
+```scala mdoc:invisible
+class SimpleLink extends Bundle {
+  val data = Output(UInt(16.W))
+  val valid = Output(Bool())
+}
+class PLink extends SimpleLink {
+  val parity = Output(UInt(5.W))
+}
+```
+```scala mdoc:compile-only
 val f = Module(new Filter(new PLink))
 ```
 
 A generic FIFO could be defined as follows:
 
-```scala
+```scala mdoc:silent
+import chisel3.util.log2Up
+
 class DataBundle extends Bundle {
   val a = UInt(32.W)
   val b = UInt(32.W)
@@ -104,8 +119,8 @@ class Fifo[T <: Data](gen: T, n: Int) extends Module {
     val enqDat = Input(gen)
     val deqDat = Output(gen)
   })
-  val enqPtr     = RegInit(0.asUInt(sizeof(n).W))
-  val deqPtr     = RegInit(0.asUInt(sizeof(n).W))
+  val enqPtr     = RegInit(0.U((log2Up(n)).W))
+  val deqPtr     = RegInit(0.U((log2Up(n)).W))
   val isFull     = RegInit(false.B)
   val doEnq      = io.enqRdy && io.enqVal
   val doDeq      = io.deqRdy && io.deqVal
@@ -118,7 +133,7 @@ class Fifo[T <: Data](gen: T, n: Int) extends Module {
   enqPtr := Mux(doEnq, enqPtrInc, enqPtr)
   deqPtr := Mux(doDeq, deqPtrInc, deqPtr)
   isFull := isFullNext
-  val ram = Mem(n)
+  val ram = Mem(n, gen)
   when (doEnq) {
     ram(enqPtr) := io.enqDat
   }
@@ -130,13 +145,20 @@ class Fifo[T <: Data](gen: T, n: Int) extends Module {
 
 An Fifo with 8 elements of type DataBundle could then be instantiated as:
 
-```scala
+```scala mdoc:compile-only
 val fifo = Module(new Fifo(new DataBundle, 8))
 ```
 
 It is also possible to define a generic decoupled (ready/valid) interface:
+```scala mdoc:invisible:reset
+import chisel3._
+class DataBundle extends Bundle {
+  val a = UInt(32.W)
+  val b = UInt(32.W)
+}
+```
 
-```scala
+```scala mdoc:silent
 class DecoupledIO[T <: Data](data: T) extends Bundle {
   val ready = Input(Bool())
   val valid = Output(Bool())
@@ -147,28 +169,30 @@ class DecoupledIO[T <: Data](data: T) extends Bundle {
 This template can then be used to add a handshaking protocol to any
 set of signals:
 
-```scala
+```scala mdoc:silent
 class DecoupledDemo extends DecoupledIO(new DataBundle)
 ```
 
 The FIFO interface can be now be simplified as follows:
 
-```scala
+```scala mdoc:silent
 class Fifo[T <: Data](data: T, n: Int) extends Module {
   val io = IO(new Bundle {
     val enq = Flipped(new DecoupledIO(data))
     val deq = new DecoupledIO(data)
   })
-  ...
+  // ...
 }
 ```
 
-# Parametrization based on Modules
+## Parametrization based on Modules
 
 You can also parametrize modules based on other modules rather than just types. The following is an example of a module parametrized by other modules as opposed to e.g. types.
 
-```scala
-import chisel3.experimental.{BaseModule, RawModule}
+```scala mdoc:silent
+import chisel3.RawModule
+import chisel3.experimental.BaseModule
+import chisel3.stage.ChiselStage
 
 // Provides a more specific interface since generic Module
 // provides no compile-time information on generic module's IOs.
@@ -204,6 +228,10 @@ class X[T <: BaseModule with MyAdder](genT: => T) extends Module {
     subMod.in2 := io.in2
 }
 
-println(chisel3.Driver.emitVerilog(new X(new Mod1)))
-println(chisel3.Driver.emitVerilog(new X(new Mod2)))
+println(ChiselStage.emitVerilog(new X(new Mod1)))
+println(ChiselStage.emitVerilog(new X(new Mod2)))
+```
+```scala mdoc:passthrough
+println(ChiselStage.emitVerilog(new X(new Mod1)))
+println(ChiselStage.emitVerilog(new X(new Mod2)))
 ```
diff --git a/docs/src/wiki-deprecated/ports.md b/docs/src/explanations/ports.md
index 251ce243..ce38cf22 100644
--- a/docs/src/wiki-deprecated/ports.md
+++ b/docs/src/explanations/ports.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Ports"
 section: "chisel3"
 ---
+
+# Ports
+
 Ports are used as interfaces to hardware components.  A port is simply
 any `Data` object that has directions assigned to its members.
 
@@ -11,7 +14,10 @@ Chisel provides port constructors to allow a direction to be added
 constructors wrap the type of the port in `Input` or `Output`.
 
 An example port declaration is as follows:
-```scala
+```scala mdoc:invisible
+import chisel3._
+```
+```scala mdoc
 class Decoupled extends Bundle {
   val ready = Output(Bool())
   val data  = Input(UInt(32.W))
@@ -33,8 +39,9 @@ provide powerful wiring constructs described later.
 Chisel 3.2 introduced `DataMirror.modulePorts` which can be used to inspect the IOs of any Chisel module (this includes modules in both `import chisel3._` and `import Chisel._`, as well as BlackBoxes from each package).
 Here is an example of how to use this API:
 
-```scala
+```scala mdoc
 import chisel3.experimental.DataMirror
+import chisel3.stage.{ChiselGeneratorAnnotation, ChiselStage}
 
 class Adder extends Module {
   val a = IO(Input(UInt(8.W)))
@@ -50,18 +57,11 @@ class Test extends Module {
   adder.b := DontCare
 
   // Inspect ports of adder
-  // Prints something like this
-  /**
-    * Found port clock: Clock(IO clock in Adder)
-    * Found port reset: Bool(IO reset in Adder)
-    * Found port a: UInt<8>(IO a in Adder)
-    * Found port b: UInt<8>(IO b in Adder)
-    * Found port c: UInt<8>(IO c in Adder)
-    */
-  DataMirror.modulePorts(adder).foreach { case (name, port) => {
+  // See the result below.
+   DataMirror.modulePorts(adder).foreach { case (name, port) => {
     println(s"Found port $name: $port")
   }}
 }
 
-chisel3.Driver.execute(Array[String](), () => new Test)
-```
+(new ChiselStage).execute(Array.empty, Seq(ChiselGeneratorAnnotation(() => new Test)))
+```
\ No newline at end of file
diff --git a/docs/src/wiki-deprecated/printing.md b/docs/src/explanations/printing.md
index 36dcfaae..abd1a427 100644
--- a/docs/src/wiki-deprecated/printing.md
+++ b/docs/src/explanations/printing.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Printing"
 section: "chisel3"
 ---
+
+# Printing in Chisel
+
 Chisel provides the `printf` function for debugging purposes. It comes in two flavors:
 
 * [Scala-style](#scala-style)
@@ -12,14 +15,17 @@ Chisel provides the `printf` function for debugging purposes. It comes in two fl
 
 Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `p` which can be used as follows:
 
-```scala
+```scala mdoc:invisible
+import chisel3._
+```
+```scala mdoc:compile-only
 val myUInt = 33.U
 printf(p"myUInt = $myUInt") // myUInt = 33
 ```
 
 Note that when concatenating `p"..."` strings, you need to start with a `p"..."` string:
 
-```scala
+```scala mdoc:compile-only
 // Does not interpolate the second string
 val myUInt = 33.U
 printf("my normal string" + p"myUInt = $myUInt")
@@ -29,7 +35,8 @@ printf("my normal string" + p"myUInt = $myUInt")
 
 Other formats are available as follows:
 
-```scala
+```scala mdoc:compile-only
+val myUInt = 33.U
 // Hexadecimal
 printf(p"myUInt = 0x${Hexadecimal(myUInt)}") // myUInt = 0x21
 // Binary
@@ -44,8 +51,8 @@ We recognize that the format specifiers are verbose, so we are working on a more
 
 Chisel provides default custom "pretty-printing" for Vecs and Bundles. The default printing of a Vec is similar to printing a Seq or List in Scala while printing a Bundle is similar to printing a Scala Map.
 
-```scala
-val myVec = Vec(5.U, 10.U, 13.U)
+```scala mdoc:compile-only
+val myVec = VecInit(5.U, 10.U, 13.U)
 printf(p"myVec = $myVec") // myVec = Vec(5, 10, 13)
 
 val myBundle = Wire(new Bundle {
@@ -61,7 +68,7 @@ printf(p"myBundle = $myBundle") // myBundle = Bundle(a -> 3, b -> 11)
 
 Chisel also provides the ability to specify _custom_ printing for user-defined Bundles.
 
-```scala
+```scala mdoc:compile-only
 class Message extends Bundle {
   val valid = Bool()
   val addr = UInt(32.W)
@@ -124,7 +131,7 @@ Note that single quotes do not require escaping, but are legal to escape.
 
 Thus printf can be used in a way very similar to how it is used in C:
 
-```scala
+```scala mdoc:compile-only
 val myUInt = 32.U
 printf("myUInt = %d", myUInt) // myUInt = 32
 ```
diff --git a/docs/src/wiki-deprecated/reset.md b/docs/src/explanations/reset.md
index f5e4a24a..a99a39e3 100644
--- a/docs/src/wiki-deprecated/reset.md
+++ b/docs/src/explanations/reset.md
@@ -4,6 +4,8 @@ title:  "Reset"
 section: "chisel3"
 ---
 
+# Reset
+
 ```scala mdoc:invisible
 import chisel3._
 
diff --git a/docs/src/wiki-deprecated/sequential-circuits.md b/docs/src/explanations/sequential-circuits.md
index 10294403..938416ac 100644
--- a/docs/src/wiki-deprecated/sequential-circuits.md
+++ b/docs/src/explanations/sequential-circuits.md
@@ -3,8 +3,15 @@ layout: docs
 title:  "Sequential Circuits"
 section: "chisel3"
 ---
+
+# Sequential Circuits
+
+```scala mdoc:invisible
+import chisel3._
+val in = Bool()
+```
 The simplest form of state element supported by Chisel is a positive edge-triggered register, which can be instantiated as:
-```scala
+``` scala mdoc:compile-only
 val reg = RegNext(in)
 ```
 This circuit has an output that is a copy of the input signal `in` delayed by one clock cycle. Note that we do not have to specify the type of Reg as it will be automatically inferred from its input when instantiated in this way. In the current version of Chisel, clock and reset are global signals that are implicitly included where needed.
@@ -12,25 +19,26 @@ This circuit has an output that is a copy of the input signal `in` delayed by on
 Note that registers which do not specify an initial value will not change value upon toggling the reset signal.
 
 Using registers, we can quickly define a number of useful circuit constructs. For example, a rising-edge detector that takes a boolean signal in and outputs true when the current value is true and the previous value is false is given by:
-```scala
+
+```scala mdoc:silent
 def risingedge(x: Bool) = x && !RegNext(x)
 ```
 Counters are an important sequential circuit. To construct an up-counter that counts up to a maximum value, max, then wraps around back to zero (i.e., modulo max+1), we write:
-```scala
+```scala mdoc:silent
 def counter(max: UInt) = {
-  val x = RegInit(0.asUInt(max.getWidth))
+  val x = RegInit(0.asUInt(max.getWidth.W))
   x := Mux(x === max, 0.U, x + 1.U)
   x
 }
 ```
 The counter register is created in the counter function with a reset value of 0 (with width large enough to hold max), to which the register will be initialized when the global reset for the circuit is asserted. The := assignment to x in counter wires an update combinational circuit which increments the counter value unless it hits the max at which point it wraps back to zero. Note that when x appears on the right-hand side of an assignment, its output is referenced, whereas when on the left-hand side, its input is referenced.
 Counters can be used to build a number of useful sequential circuits. For example, we can build a pulse generator by outputting true when a counter reaches zero:
-```scala
+```scala mdoc:silent
 // Produce pulse every n cycles.
 def pulse(n: UInt) = counter(n - 1.U) === 0.U
 ```
 A square-wave generator can then be toggled by the pulse train, toggling between true and false on each pulse:
-```scala
+```scala mdoc:silent
 // Flip internal state when input true.
 def toggle(p: Bool) = {
   val x = RegInit(false.B)
@@ -38,5 +46,5 @@ def toggle(p: Bool) = {
   x
 }
 // Square wave of a given period.
-def squareWave(period: UInt) = toggle(pulse(period/2))
+def squareWave(period: UInt) = toggle(pulse(period >> 1))
 ```
diff --git a/docs/src/wiki-deprecated/supported-hardware.md b/docs/src/explanations/supported-hardware.md
index 97f82698..fe3909e7 100644
--- a/docs/src/wiki-deprecated/supported-hardware.md
+++ b/docs/src/explanations/supported-hardware.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Supported Hardware"
 section: "chisel3"
 ---
+
+# Supported Hardware
+
 While Chisel focuses on binary logic, Chisel can support analog and tri-state wires with the `Analog` type - see [Datatypes in Chisel](data-types).
 
 We focus on binary logic designs as they constitute the vast majority of designs in practice. Tri-state logic are poorly supported standard industry flows and require special/controlled hard macros in order to be done.
diff --git a/docs/src/wiki-deprecated/unconnected-wires.md b/docs/src/explanations/unconnected-wires.md
index 1fa12e59..48012d12 100644
--- a/docs/src/wiki-deprecated/unconnected-wires.md
+++ b/docs/src/explanations/unconnected-wires.md
@@ -3,10 +3,13 @@ layout: docs
 title:  "Unconnected Wires"
 section: "chisel3"
 ---
-The Invalidate API [(#645)](https://github.com/freechipsproject/chisel3/pull/645) adds support to chisel
+
+# Unconnected Wires
+
+The Invalidate API [(#645)](https://github.com/freechipsproject/chisel3/pull/645) adds support to Chisel
 for reporting unconnected wires as errors.
 
-Prior to this pull request, chisel automatically generated a firrtl `is invalid` for `Module IO()`, and each `Wire()` definition.
+Prior to this pull request, Chisel automatically generated a firrtl `is invalid` for `Module IO()`, and each `Wire()` definition.
 This made it difficult to detect cases where output signals were never driven.
 Chisel now supports a `DontCare` element, which may be connected to an output signal, indicating that that signal is intentionally not driven.
 Unless a signal is driven by hardware or connected to a `DontCare`, Firrtl will complain with a "not fully initialized" error.
@@ -14,23 +17,41 @@ Unless a signal is driven by hardware or connected to a `DontCare`, Firrtl will
 ### API
 
 Output signals may be connected to DontCare, generating a `is invalid` when the corresponding firrtl is emitted.
-```scala
+
+```scala mdoc:invisible
+import chisel3._
+```
+```scala mdoc:silent
+
+class Out extends Bundle { 
+  val debug = Bool()
+  val debugOption = Bool()
+}
+val io = new Bundle { val out = new Out }
+```
+
+```scala mdoc:compile-only
 io.out.debug := true.B
 io.out.debugOption := DontCare
 ```
+
 This indicates that the signal `io.out.debugOption` is intentionally not driven and firrtl should not issue a "not fully initialized"
 error for this signal.
 
 This can be applied to aggregates as well as individual signals:
-```scala
-{
-  ...
+```scala mdoc:invisible
+import chisel3._
+```
+```scala mdoc:silent
+import chisel3._
+class ModWithVec extends Module {
+  // ...
   val nElements = 5
   val io = IO(new Bundle {
     val outs = Output(Vec(nElements, Bool()))
   })
   io.outs <> DontCare
-  ...
+  // ...
 }
 
 class TrivialInterface extends Bundle {
@@ -38,11 +59,11 @@ class TrivialInterface extends Bundle {
   val out = Output(Bool())
 }
 
-{
-  ...
+class ModWithTrivalInterface extends Module {
+  // ...
   val io = IO(new TrivialInterface)
   io <> DontCare
-  ...
+  // ...
 }
 ```
 
@@ -51,26 +72,31 @@ and `true` in `Strict` mode.
 
 You can selectively enable this for Chisel2 compatibility mode by providing your own explicit `compileOptions`,
 either for a group of Modules (via inheritance):
-```scala
-abstract class ExplicitInvalidateModule extends Module()(chisel3.core.ExplicitCompileOptions.NotStrict.copy(explicitInvalidate = true))
+```scala mdoc:silent
+abstract class ExplicitInvalidateModule extends Module()(chisel3.ExplicitCompileOptions.NotStrict.copy(explicitInvalidate = true))
 ```
 or on a per-Module basis:
-```scala
+```scala mdoc:silent
 class MyModule extends Module {
-  override val compileOptions = chisel3.core.ExplicitCompileOptions.NotStrict.copy(explicitInvalidate = true)
-  ...
+  override val compileOptions = chisel3.ExplicitCompileOptions.NotStrict.copy(explicitInvalidate = true)
+  val io = IO(new Bundle { /* ... */ } )
+  // ...
 }
 ```
 
 Or conversely, disable this stricter checking (which is now the default in pure chisel3):
-```scala
-abstract class ImplicitInvalidateModule extends Module()(chisel3.core.ExplicitCompileOptions.Strict.copy(explicitInvalidate = false))
+```scala mdoc:silent
+abstract class ImplicitInvalidateModule extends Module()(chisel3.ExplicitCompileOptions.Strict.copy(explicitInvalidate = false))
 ```
 or on a per-Module basis:
-```scala
+```scala mdoc:invisible:reset
+import chisel3._
+```
+```scala mdoc:silent
 class MyModule extends Module {
-  override val compileOptions = chisel3.core.ExplicitCompileOptions.Strict.copy(explicitInvalidate = false)
-  ...
+  override val compileOptions = chisel3.ExplicitCompileOptions.Strict.copy(explicitInvalidate = false)
+  val io = IO(new Bundle { /* ... */ } )
+  // ...
 }
 ```
 
diff --git a/docs/src/wiki-deprecated/width-inference.md b/docs/src/explanations/width-inference.md
index 60f9d519..66d9736d 100644
--- a/docs/src/wiki-deprecated/width-inference.md
+++ b/docs/src/explanations/width-inference.md
@@ -3,6 +3,9 @@ layout: docs
 title:  "Width Inference"
 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.
 
 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.
diff --git a/docs/src/introduction.md b/docs/src/introduction.md
new file mode 100644
index 00000000..3b68aae2
--- /dev/null
+++ b/docs/src/introduction.md
@@ -0,0 +1,41 @@
+---
+layout: docs
+title:  "Introduction"
+section: "chisel3"
+---
+
+# An Introduction to Chisel
+
+_Chisel_ (Constructing
+Hardware In a Scala Embedded Language) is a hardware
+construction language embedded in the high-level programming language
+Scala.
+ Chisel is a library of special class
+definitions, predefined objects, and usage conventions within [Scala](https://www.scala-lang.org/),
+so when you write Chisel you are actually writing a Scala
+program that constructs a hardware graph.
+As you gain experience and want to make your code simpler or more
+reusable, you will find it important to leverage the underlying power
+of the Scala language. We recommend you consult one of the excellent
+Scala books to become more expert in Scala programming.
+
+For a tutorial covering both Chisel and Scala, see the 
+[**online Chisel Bootcamp**](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master).
+
+For quick reference "How-To" guides see the [Cookbooks](cookbooks/cookbooks).
+
+For a deeper introduction to key concepts in  Chisel see the [Explanations](explanations/explanations).
+
+The [API Documentation](https://www.chisel-lang.org/api/) gives the detailed reference for the Chisel source code.
+Note that previous versions can be found via the sidebar menu at [https://www.chisel-lang.org/chisel3].
+
+The [Resources](resources/resources) provides links to other useful resources for learning and working with Chisel.
+
+The [Appendix](appendix/appendix) covers some more advanced topics.
+
+The [Developers](developers/developers) section provides information for those working on the Chisel library itself.
+
+>Throughout these pages, we format commentary on our design choices as in
+this paragraph.  You should be able to skip the commentary sections
+and still fully understand how to use Chisel, but we hope you'll find
+them interesting.
diff --git a/docs/src/wiki-deprecated/faqs.md b/docs/src/resources/faqs.md
index 45694cdc..debdfcbe 100644
--- a/docs/src/wiki-deprecated/faqs.md
+++ b/docs/src/resources/faqs.md
@@ -4,6 +4,8 @@ title:  "Frequently Asked Questions"
 section: "chisel3"
 ---
 
+# Frequently Asked Questions
+
 * [Where should I start if I want to learn Chisel?](#where-should-i-start-if-i-want-to-learn-chisel)
 * [How do I ... in Chisel?](#how-do-i-do--eg-like-that-in-verilog-in-chisel)
 * [How can I contribute to Chisel?](#how-can-i-contribute-to-chisel)
@@ -24,7 +26,7 @@ We recommend the [Chisel Bootcamp](https://github.com/freechipsproject/chisel-bo
 
 ### How do I do ... (e.g. like that in Verilog) in Chisel?
 
-See the [cookbook](cookbook).
+See the [cookbooks](../cookbooks/cookbook).
 
 ### How can I contribute to Chisel?
 
@@ -78,7 +80,7 @@ Chisel Modules are written by defining a [Scala class](http://docs.scala-lang.or
 
 ### Why Chisel?
 
-Borrowed from [Chisel Introduction](introduction)
+Borrowed from [Chisel Motivation](../explanations/motivation)
 
 >We were motivated to develop a new hardware language by years of
 struggle with existing hardware description languages in our research
@@ -126,34 +128,47 @@ I wrote a module and I want to see the Verilog; what do I do?
 
 Here's a simple hello world module in a file HelloWorld.scala.
 
+
 ```scala
 package intro
+```
+```scala mdoc:silent
 import chisel3._
 class HelloWorld extends Module {
   val io = IO(new Bundle{})
   printf("hello world\n")
 }
 ```
+
 Add the following
-```scala
-object HelloWorld extends App {
-  chisel3.Driver.execute(args, () => new HelloWorld)
+```scala mdoc:silent
+import chisel3.stage.ChiselStage
+object VerilogMain extends App {
+  (new ChiselStage).emitVerilog(new HelloWorld)
 }
 ```
 Now you can get some Verilog. Start sbt:
 ```
 bash> sbt
-> run-main intro.HelloWorld
-[info] Running examples.HelloWorld
+> run-main intro.VerilogMain
+[info] Running intro.VerilogMain
 [info] [0.004] Elaborating design...
 [info] [0.100] Done elaborating.
 [success] Total time: 1 s, completed Jan 12, 2017 6:24:03 PM
 ```
 or as a one-liner:
 ```
-bash> sbt 'runMain intro.HelloWorld'
+bash> sbt 'runMain intro.VerilogMain'
+```
+After either of the above there will be a HelloWorld.v file in the current directory:
+```scala mdoc:invisible
+val verilog = ChiselStage.emitVerilog(new HelloWorld)
+```
+```scala mdoc:passthrough
+println("```verilog")
+println(verilog)
+println("```")
 ```
-After either of the above there will be a HelloWorld.v file in the current directory.
 
 You can see additional options with
 ```
@@ -172,61 +187,84 @@ Alternatively, you can also use the sbt console to invoke the Verilog driver:
 $ sbt
 > console
 [info] Starting scala interpreter...
-[info]
-Welcome to Scala 2.11.8 (OpenJDK 64-Bit Server VM, Java 1.8.0_121).
+Welcome to Scala 2.12.13 (OpenJDK 64-Bit Server VM, Java 1.8.0_275).
 Type in expressions for evaluation. Or try :help.
-scala> chisel3.Driver.execute(Array[String](), () => new HelloWorld)
+
+scala> (new chisel3.stage.ChiselStage).emitVerilog(new HelloWorld())
 chisel3.Driver.execute(Array[String](), () => new HelloWorld)
-[info] [0.014] Elaborating design...
-[info] [0.306] Done elaborating.
-Total FIRRTL Compile Time: 838.8 ms
-res3: chisel3.ChiselExecutionResult = [...]
+Elaborating design...
+Done elaborating.
+res1: String =
+"module HelloWorld(
+  input   clock,
+  input   reset
+);
+...
 ```
 
 As before, there should be a HelloWorld.v file in the current directory.
 
+Note: Using the following, without the `new`,
+will ONLY return the string representation, and will not emit a `.v` file:
+
+```scala mdoc:silent
+ChiselStage.emitVerilog(new HelloWorld())
+```
+
 ### Get me FIRRTL
 
 If for some reason you don't want the Verilog (e.g. maybe you want to run some custom transformations before exporting to Verilog), then use something along these lines (replace Multiplier with your module):
 
 ```scala
 package intro
+```
+```scala mdoc:silent:reset
 
 import chisel3._
-import java.io.File
+import chisel3.stage.ChiselStage
 
-object Main extends App {
-  val f = new File("Multiplier.fir")
-  chisel3.Driver.dumpFirrtl(chisel3.Driver.elaborate(() => new Multiplier), Option(f))
+class MyFirrtlModule extends Module {
+  val io = IO(new Bundle{})
+}
+
+object FirrtlMain extends App {
+  (new ChiselStage).emitFirrtl(new MyFirrtlModule)
 }
 ```
 
 Run it with:
 
 ```
-sbt 'runMain intro.Main'
+sbt 'runMain intro.FirrtlMain'
+```
+```scala mdoc:invisible
+val theFirrtl = ChiselStage.emitFirrtl(new MyFirrtlModule)
+```
+```scala mdoc:passthrough
+println("```")
+println(theFirrtl)
+println("```")
 ```
 
-Alternatively, you can also use the sbt console to invoke the FIRRTL driver directly (replace HelloWorld with your module name):
+Alternatively, you can also use the sbt console to invoke the FIRRTL driver directly (replace MyFirrtlModule with your module name):
 
 ```
 $ sbt
 > console
 [info] Starting scala interpreter...
-[info]
-Welcome to Scala 2.11.11 (OpenJDK 64-Bit Server VM, Java 1.8.0_151).
+Welcome to Scala 2.12.13 (OpenJDK 64-Bit Server VM, Java 1.8.0_275).
 Type in expressions for evaluation. Or try :help.
-scala> chisel3.Driver.dumpFirrtl(chisel3.Driver.elaborate(() => new HelloWorld), Option(new java.io.File("output.fir")))
-chisel3.Driver.dumpFirrtl(chisel3.Driver.elaborate(() => new HelloWorld), Option(new java.io.File("output.fir")))
-[info] [0.000] Elaborating design...
-[info] [0.001] Done elaborating.
-res3: java.io.File = output.fir
+
+scala> (new chisel3.stage.ChiselStage).emitFirrtl(new MyFirrtlModule)
+Elaborating design...
+Done elaborating.
+res3: String = ...
 ```
 
 ### Why doesn't Chisel tell me which wires aren't connected?
 
 As of commit [c313e13](https://github.com/freechipsproject/chisel3/commit/c313e137d4e562ef20195312501840ceab8cbc6a) it can!
-Please visit the wiki page [Unconnected Wires](unconnected-wires) for details.
+Read more at [Unconnected Wires](../explanations/unconnected-wires) for details.
 
 ### What does `Reference ... is not fully initialized.` mean?
 
@@ -235,7 +273,7 @@ It means that you have unconnected wires in your design which could be an indica
 In Chisel2 compatibility mode (`NotStrict` compile options), chisel generates firrtl code that disables firrtl's initialized wire checks.
 In pure chisel3 (`Strict` compile options), the generated firrtl code does not contain these disablers (`is invalid`).
 Output wires that are not driven (not connected) are reported by firrtl as `not fully initialized`.
-Please visit the wiki page [Unconnected Wires](unconnected-wires) for details on solving the problem.
+Read more at [Unconnected Wires](../explanations/unconnected-wires) for details on solving the problem.
 
 ### Can I specify behavior before and after generated initial blocks?
 Users may define the following macros if they wish to specify behavior before or after emitted initial blocks.
diff --git a/docs/src/wiki-deprecated/resources.md b/docs/src/resources/resources.md
index 8b75be49..fadd26a1 100644
--- a/docs/src/wiki-deprecated/resources.md
+++ b/docs/src/resources/resources.md
@@ -4,6 +4,8 @@ title:  "Resources and References"
 section: "chisel3"
 ---
 
+# Chisel Resources
+
 The *best resource* to learn about Chisel is the [**online Chisel Bootcamp**](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master). This runs in your browser and assumes no prior Scala knowledge. (You may also run this locally via the [backing chisel-bootcamp GitHub repository](https://github.com/freechipsproject/chisel-bootcamp).)
 
 When you're ready to build your own circuits in Chisel, **we recommend starting from the [Chisel Template](https://github.com/freechipsproject/chisel-template) repository**, which provides a pre-configured project, example design, and testbench. Follow the [chisel-template readme](https://github.com/freechipsproject/chisel-template) to get started.
@@ -12,3 +14,4 @@ The following additional resources and references may be useful:
 
 - [Chisel Cheatsheet](https://github.com/freechipsproject/chisel-cheatsheet/releases/latest/download/chisel_cheatsheet.pdf)
 - [Digital Design With Chisel](https://github.com/schoeberl/chisel-book)
+- [Frequently Asked Questions](faqs)
diff --git a/docs/src/wiki-deprecated/interval-type.md b/docs/src/wiki-deprecated/interval-type.md
deleted file mode 100644
index 7f33461e..00000000
--- a/docs/src/wiki-deprecated/interval-type.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# Intervals
-**Intervals** are a new experimental numeric type that comprises UInt, SInt and FixedPoint numbers.
-It augments these types with range information, i.e. upper and lower numeric bounds.
-This information can be used to exercise tighter programmatic control over the ultimate widths of
-signals in the final circuit.  The **Firrtl** compiler can infer this range information based on 
-operations and earlier values in the circuit. Intervals support all the ordinary bit and arithmetic operations
-associated with UInt, SInt, and FixedPoint and adds the following methods for manipulating the range of
-a **source** Interval with the IntervalRange of **target** Interval 
-
-### Clip -- Fit the value **source** into the IntervalRange of **target**, saturate if out of bounds
-The clip method applied to an interval creates a new interval based on the argument to clip,
-and constructs the necessary hardware so that the source Interval's value will be mapped into the new Interval.
-Values that are outside the result range will be pegged to either maximum or minimum of result range as appropriate.
-
-> Generates necessary hardware to clip values, values greater than range are set to range.high, values lower than range are set to range min.
-
-### Wrap -- Fit the value **source** into the IntervalRange of **target**, wrapping around if out of bounds
-The wrap method applied to an interval creates a new interval based on the argument to wrap,
-and constructs the necessary
-hardware so that the source Interval's value will be mapped into the new Interval.
-Values that are outside the result range will be wrapped until they fall within the result range.
-
-> Generates necessary hardware to wrap values, values greater than range are set to range.high, values lower than range are set to range min.
-
-> Does not handle out of range values that are less than half the minimum or greater than twice maximum
-
-### Squeeze -- Fit the value **source** into the smallest IntervalRange based on source and target.
-The squeeze method applied to an interval creates a new interval based on the argument to clip, the two ranges must overlap
-behavior of squeeze with inputs outside of the produced range is undefined.
-
-> Generates no hardware, strictly a sizing operation
-
-#### Range combinations
-
-| Condition | A.clip(B) | A.wrap(B) | A.squeeze(B) |
-| --------- | --------------- | --------------- | --------------- |
-| A === B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
-| A contains B   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
-| B contains A   | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
-| A min < B min, A max in B  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
-| A min in B, A max > B max  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  | max(Alo, Blo), min(Ahi, Bhi)  |
-| A strictly less than B   | error               | error               | error               |
-| A strictly greater than B   | error               | error               | error               |
-
-
-### Applying binary point operators to an Interval
-
-Consider a Interval with a binary point of 3: aaa.bbb 
-
-| operation | after operation | binary point | lower | upper | meaning | 
-| --------- | --------------- | ------------ | ----- | ----- | ------- |
-| setBinaryPoint(2) | aaa.bb |  2 | X | X  | set the precision |
-| shiftLeftBinaryPoint(2) | a.aabbb |  5 | X | X  | increase the precision |
-| shiftRighBinaryPoint(2) | aaaa.b |  1 | X | X  | reduce the precision |
-