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

4 files changed, 364 insertions, 0 deletions

diff --git a/docs/src/developers/developers.md b/docs/src/developers/developers.md
new file mode 100644
index 00000000..b2b5dff8
--- /dev/null
+++ b/docs/src/developers/developers.md
@@ -0,0 +1,12 @@
+---
+layout: docs
+title:  "Developers"
+section: "chisel3"
+---
+
+# Developer Documentation
+
+Tips and tricks for Chisel developers:
+
+* [Embedding Chisel as an sbt subproject](sbt-subproject)
+* [Test Coverage](test-coverage)
diff --git a/docs/src/developers/sbt-subproject.md b/docs/src/developers/sbt-subproject.md
new file mode 100644
index 00000000..44d2916b
--- /dev/null
+++ b/docs/src/developers/sbt-subproject.md
@@ -0,0 +1,36 @@
+---
+layout: docs
+title:  "Developers"
+section: "chisel3"
+---
+
+# 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.
+For sbt-based builds there are fundamentally two ways to do this:
+* provide a library dependency on the published Chisel3 jars via sbt's `libraryDependencies` setting,
+* clone the Chisel3 git repository and include the source code as a subproject of a dependent project.
+
+The former of these two approaches is used by the chisel-tutorial project.
+It is the simplest approach and assumes you do not require tight control over Chisel3 source code and are content with the
+published release versions of Chisel3.
+
+The latter approach should be used by Chisel3 projects that require finer control over Chisel3 source code.
+
+It's hard to predict in advance the future requirements of a project, and it would be advantageous to be able to
+switch between the two approaches relatively easily.
+In order to accomplish this, we provide the `sbt-chisel-dep` plugin that allows the developer to concisely specify
+Chisel3 subproject dependencies and switch between subproject and library dependency support based on the presence of
+a directory (or symbolic link) in the root of the dependent project.
+
+The chisel-template project uses this plugin to support switching between either dependency (subproject or library).
+By default, the chisel-template project does not contain a chisel3 subproject directory, and hence, uses a library dependency
+on chisel3 (and related Chisel3 projects).
+However, if you clone the chisel3 GitHub project from the root directory of the chisel-template project, creating a chisel3
+subdirectory, the `sbt-chisel-dep` plugin will take note of the chisel3 project subdirectory,
+and provide an sbt subproject dependency in place of the library dependency.
+
+Checkout the [README for the `sbt-chisel-dep`](https://github.com/ucb-bar/sbt-chisel-dep) project for instructions on its usage.
+
+Example versions of the build.sbt and specification of the sbt-chisel-dep plugin are available from the [skeleton branch of the chisel-template repository](https://github.com/ucb-bar/chisel-template/tree/skeleton).
diff --git a/docs/src/developers/style.md b/docs/src/developers/style.md
new file mode 100644
index 00000000..80e1e083
--- /dev/null
+++ b/docs/src/developers/style.md
@@ -0,0 +1,293 @@
+---
+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/). 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.
+
+## Filenames
+The source file name consists of the case-sensitive name of the top-level class
+it contains, plus ".scala".
+
+## Packages
+
+Package definitions must contain the full path to the package from scala. If
+you create a subpackage, it should go in a subdirectory.
+
+    package directory.name.to.get.you.to.your.source
+
+As in Scala, packages follow the [Java package naming convention](https://google.github.io/styleguide/javaguide.html#s5.2.1-package-names).
+Note that these guidelines call for all lowercase, no underscores.
+
+```scala
+// Do this
+package hardware.chips.topsecret.masterplan
+
+// Not this
+package hardware.chips.veryObvious.bad_style
+```
+
+We also suggest you do not use chisel3 as a package, and especially do not use it
+as the final (innermost) package.
+
+```scala
+// Don't do this
+package hardware.chips.newchip.superfastcomponent.chisel3
+
+// This will lead to instantiating package members like so:
+val module = Module(new chisel3.FastModule)
+
+// Which collides with the chisel namespace
+import chisel3._
+```
+
+## Imports
+Avoid wildcard ( ._ ) imports, with the exception of chisel3._
+All other imports must call out used methods.
+`import chisel3._` must be first, and separated from remaining imports with an extra blank line.
+
+**Reason:** This makes it clear where methods are defined.
+
+Any remaining imports must be listed alphabetically.
+
+```scala
+import chisel3._
+
+import the.other.thing.that.i.reference.inline
+import the.other.things.that.i.reference.{ClassOne, ClassTwo}
+
+
+val myInline = inline.MakeAnInline()
+val myClassOne = new ClassOne
+```
+
+## Tests
+Test classes are named starting with the name of the class they are testing, and
+ending with "Test".
+Test files must start with the name of the class you are testing and end with
+"Test.scala".
+Test files should reside in a subdirectory called "tests".
+The tests package should be composed of the package class you are testing.
+
+```scala
+package class.under.test.class
+package tests
+```
+
+## Comments
+We use scaladoc to automatically generate documentation from the source code.
+
+```scala
+/** Multiple lines of ScalaDoc text are written here,
+  * wrapped normally...
+  */
+public int method(String p1) { ... }
+```
+
+... or in this single-line example:
+
+```scala
+/** An especially short bit of Javadoc. */
+```
+
+Write documentation as if the person reading it knows more about Scala and
+Chisel than you. If you find comments in the code consider breaking them up
+into seperate methods.
+
+## Module Classes and Instances
+
+Modules can take different forms in Chisel. The first form is similar to Verilog, where
+you instance the module and then hook it up. In this case `Module(new MyMod())` is
+returning a reference to the module.
+
+```scala
+val myMod = Module(new MyMod())
+myMod.io <> hookUp
+```
+
+The second form is a more programmatic inline style with factory methods. In this case,
+Queue is actually returning the part of the IO bundle representing the queue's
+output. The factory method takes the input IO to the queue and an optional parameter
+for depth.
+
+```scala
+val queueOut = Queue(queueIn, depth=10)
+```
+
+The latter can be used for composing multiple functions into a single line.
+
+```scala
+val queueOut = Queue(
+  Arbitrate.byRoundRobin(
+    Queue(a), // depth assumed to be 1
+    Queue(b, depth=3),
+    Queue(c, depth=4)
+  ),
+  depth=10
+)
+```
+
+## Naming Conventions
+
+Chisel follows the [Scala Naming Conventions](http://docs.scala-lang.org/style/naming-conventions.html).
+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?
+
+The compiler inserts underscores when splitting Chisel/FIRRTL aggregate types
+into Verilog types. The compiler uses underscores to preserve the original
+structure of the data in the resulting Verilog. Because of the special meaning
+of underscores in Chisel-generated Verilog, their use in naming is **strongly**
+discouraged.
+
+Consider the following Chisel code:
+
+```scala
+val msg = Wire(new Bundle {
+  val valid = Bool()
+  val addr = UInt(32)
+  val data = UInt(64)
+})
+val msg_rec = Wire(Bool())
+```
+
+Which compiles to the Verilog:
+
+```verilog
+wire  msg_valid;
+wire [31:0] msg_addr;
+wire [63:0] msg_data;
+wire  msg_rec;
+```
+
+The Verilog maintains the structure of the original aggregate wire `msg`.
+However, because we named another variable `msg_rec`, it appears in the Verilog
+as if `msg` had 4 fields instead of its actual 3! If we instead follow the
+lowerCamelCase for values naming convention, the resulting Verilog makes more
+sense:
+
+```scala
+val msg = Wire(new Bundle {
+  val valid = Bool()
+  val addr = UInt(32)
+  val data = UInt(64)
+})
+val msgRec = Wire(Bool())
+```
+
+And its resulting Verilog:
+
+```verilog
+wire  msg_valid;
+wire [31:0] msg_addr;
+wire [63:0] msg_data;
+wire  msgRec;
+```
+
+Much better.
+
+### Modules and Bundles (Classes, Traits, and Objects)
+
+Modules are Scala classes and thus use UpperCamelCase.
+
+```scala
+class ModuleNamingExample extends Module {
+  ...
+}
+```
+
+Similarly, other classes (Chisel & Scala) should be UpperCamelCase as well.
+
+```scala
+trait UsefulScalaUtilities {
+  def isEven(n: Int): Boolean = (n % 2) == 0
+  def isOdd(n: Int): Boolean = !isEven(n)
+}
+
+class MyCustomBundle extends Bundle {
+  ...
+}
+// Companion object to MyCustomBundle
+object MyCustomBundle {
+  ...
+}
+
+```
+
+### Values and Methods
+
+Values and methods should use lowerCamelCase. (Unless the value is a constant.)
+
+```scala
+val mySuperReg = Reg(init = 0.asUInt(32))
+def myImportantMethod(a: UInt): Bool = a < 23.asUInt
+```
+
+### Constants
+
+Unlike the Google Java style, constants use UpperCamelCase, which is in line
+with the official [Scala Naming
+Conventions](https://docs.scala-lang.org/style/naming-conventions.html).
+Constants are final fields (val or object) whose contents are deeply immutable
+and belong to a package object or an object. Examples:
+
+```scala
+// Constants
+object Constants {
+  val Number = 5
+  val Names = "Ed" :: "Ann" :: Nil
+  val Ages = Map("Ed" -> 35, "Ann" -> 32)
+}
+
+// Not constants
+class NonConstantsInClass {
+  val inClass: String = "in-class"
+}
+
+object nonConstantsInObject {
+  var varString = "var-string"
+  val mutableCollection: scala.collection.mutable.Set[String]
+  val mutableElements = Set(mutable)
+}
+```
+
+### UpperCamelCase vs. lowerCamelCase
+
+There is more than one reasonable way to covert English prose into camel case.
+We follow the convention defined in the [Google Java style
+guide](https://google.github.io/styleguide/javaguide.html#s5.3-camel-case). The
+potentially non-obvious rule being to treat acronymns as words for the purpose
+of camel case.
+
+Note that the casing of the original words is almost entirely disregarded.
+Example:
+
+Prose form     | UpperCamelCase | lowerCamelCase | Incorrect
+:------------- | :------------- | :------------- | :------------
+find GCD       | FindGcd        | findGcd        | ~~findGCD~~
+state for FSM  | StateForFsm    | stateForFsm    | ~~stateForFSM~~
+mock dut       | MockDut        | mockDut        | ~~MockDUT~~
+FIFO Generator | FifoGenerator  | fifoGenerator  | ~~FIFOGenerator~~
diff --git a/docs/src/developers/test-coverage.md b/docs/src/developers/test-coverage.md
new file mode 100644
index 00000000..099db4bb
--- /dev/null
+++ b/docs/src/developers/test-coverage.md
@@ -0,0 +1,23 @@
+---
+layout: docs
+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.
+The tests themselves are found in `src/test/scala`.
+
+## Generating A Test Coverage Report
+
+Use the following sequence of sbt commands to generate a test coverage report:
+```
+sbt clean coverage test
+sbt coverageReport
+```
+The coverage reports should be found in `target/scala-x.yy/scoverage-report/{scoverage.xml,index.html}` where `x.yy` corresponds to the version of Scala used to compile Firrtl and the tests.
+`scoverage.xml` is useful if you want to analyze the results programmatically.
+`index.html` is designed for navigation with a web browser, allowing one to drill down to invidual statements covered (or not) by the tests.