From 7edba2d10f980016462f917c6d21d64585ddfd6b Mon Sep 17 00:00:00 2001
From: Adam Izraelevitz
Date: Fri, 21 Aug 2020 12:02:26 -0700
Subject: Added website docs and mdoc. (#1560)
* Added website docs and mdoc. Removed all warnings
* Updated README and added build to circle ci
* Added how to build documentation, deprecated wiki
* Fix copypasta
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>---
doc/images/Makefile | 12 -
doc/images/chisel_logo.png | Bin 33246 -> 0 bytes
doc/images/chisel_logo.svg | 12593 ----------------------------------------
doc/images/fir_filter.svg | 126 -
doc/images/type_hierarchy.dot | 52 -
doc/images/type_hierarchy.png | Bin 34477 -> 0 bytes
doc/images/type_hierarchy.svg | 261 -
doc/images/vec-forall.svg | 330 --
doc/style.md | 275 -
9 files changed, 13649 deletions(-)
delete mode 100644 doc/images/Makefile
delete mode 100644 doc/images/chisel_logo.png
delete mode 100644 doc/images/chisel_logo.svg
delete mode 100644 doc/images/fir_filter.svg
delete mode 100644 doc/images/type_hierarchy.dot
delete mode 100644 doc/images/type_hierarchy.png
delete mode 100644 doc/images/type_hierarchy.svg
delete mode 100644 doc/images/vec-forall.svg
delete mode 100644 doc/style.md
(limited to 'doc')
diff --git a/doc/images/Makefile b/doc/images/Makefile
deleted file mode 100644
index 20a41d1f..00000000
--- a/doc/images/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-.PHONY: all
-
-sources = \
- type_hierarchy.dot
-
-all: $(sources:%.dot=%.svg) $(sources:%.dot=%.png)
-
-%.svg: %.dot
- dot -Tsvg $< -o $@
-
-%.png: %.dot
- dot -Tpng $< -o $@
diff --git a/doc/images/chisel_logo.png b/doc/images/chisel_logo.png
deleted file mode 100644
index df7d0001..00000000
Binary files a/doc/images/chisel_logo.png and /dev/null differ
diff --git a/doc/images/chisel_logo.svg b/doc/images/chisel_logo.svg
deleted file mode 100644
index a6b1e273..00000000
--- a/doc/images/chisel_logo.svg
+++ /dev/null
@@ -1,12593 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/doc/images/fir_filter.svg b/doc/images/fir_filter.svg
deleted file mode 100644
index c2627b88..00000000
--- a/doc/images/fir_filter.svg
+++ /dev/null
@@ -1,126 +0,0 @@
-
-
\ No newline at end of file
diff --git a/doc/images/type_hierarchy.dot b/doc/images/type_hierarchy.dot
deleted file mode 100644
index d3bf6eb4..00000000
--- a/doc/images/type_hierarchy.dot
+++ /dev/null
@@ -1,52 +0,0 @@
-digraph TypeHierarchy {
- graph [rankdir=BT bgcolor="transparent"]
- { node [style=filled,shape=box]
- { node [fillcolor="#f7fbff"]
- Data
- Element
- Bits Num
- Aggregate
- VecLike
- "Chisel Internal"
- }
- { node [fillcolor="#e5f5e0"]
- Bool UInt SInt FixedPoint
- Reset
- AsyncReset
- Record
- Bundle
- Vec
- "Chisel Types"
- }
- { node [fillcolor="#fcbba1"]
- "User Types"
- Ellipsis [label="..."]
- }
-
- subgraph cluster_data_hierarchy {
- color=transparent
- Element
- Bits Num
- Reset
- Bool UInt SInt FixedPoint
- color=transparent
- Aggregate
- VecLike
- Record
- Bundle
- Vec
-
- {Aggregate Element} -> Data
- {Bits Reset} -> Element
- {FixedPoint SInt UInt} -> {Bits Num}
- Bool -> {UInt Reset}
- Ellipsis -> Bundle -> Record -> Aggregate
- Vec -> {Aggregate VecLike}
- AsyncReset -> {Element Reset}
- }
- subgraph cluster_legend {
- label=Legend
- "User Types" -> "Chisel Types" -> "Chisel Internal"
- }
- }
-}
diff --git a/doc/images/type_hierarchy.png b/doc/images/type_hierarchy.png
deleted file mode 100644
index f3947975..00000000
Binary files a/doc/images/type_hierarchy.png and /dev/null differ
diff --git a/doc/images/type_hierarchy.svg b/doc/images/type_hierarchy.svg
deleted file mode 100644
index c120daba..00000000
--- a/doc/images/type_hierarchy.svg
+++ /dev/null
@@ -1,261 +0,0 @@
-
-
-
-
-
diff --git a/doc/images/vec-forall.svg b/doc/images/vec-forall.svg
deleted file mode 100644
index 24c6a267..00000000
--- a/doc/images/vec-forall.svg
+++ /dev/null
@@ -1,330 +0,0 @@
-
-
-
-
diff --git a/doc/style.md b/doc/style.md
deleted file mode 100644
index c845f7b4..00000000
--- a/doc/style.md
+++ /dev/null
@@ -1,275 +0,0 @@
-# Chisel Style Guide
-
-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
-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 CamelCase for naming (ie. the first letter
-of each word is capitalized except sometimes the first word).
-
-### 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~~
--
cgit v1.2.3