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

3 files changed, 115 insertions, 28 deletions

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.