Chisel 3 Documentation

This directory contains documentation on the code within this repository. Documents can either be written directly in markdown, or use embedded mdoc which compiles against the chisel3 (and dependencies) codebase 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.

Our documentation is organized into the four categories as described in Divio's documentation system.

The four documentation types are:

1. Reference (source code scaladoc)
2. Explanation (src/explanations)
3. How-To Guides (src/cookbooks)
4. Tutorials (currently not located here)

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.
• Tutorials are kept in a separate repository.

This documentation is hosted on the Chisel website. Currently, edits to this repo which are backported to the most recent stable branch (3.4.x at time of writing) will be picked up automatically by the website repository and pushed live within a day or so. If you create a new document page, you probably also want to:

1. Make sure to add it to the "Contents" page of the corresponding directory cookbooks, explanations, etc.
2. Update the sidebar on the website here.

mdoc

Basic Use

To build the documentation, run docs/mdoc via SBT in the root directory. The generated documents will appear in the docs/generated folder. To iterate on the documentation, you can run docs/mdoc --watch. For more mdoc instructions you can visit their website.

Custom verilog modifier

mdoc supports custom modifiers. We have created a custom verilog modifier to enable displaying the Verilog output of Chisel.

Example use:

```scala mdoc:silent
class MyModule extends RawModule {
  val in = IO(Input(UInt(8.W)))
  val out = IO(Output(UInt(8.W)))
  out := in + 1.U
}
```
```scala mdoc:verilog
ChiselStage.emitVerilog(new MyModule)
```

The verilog modifier tells mdoc to run the Scala block, requiring that each Statement returns a String. It will then concatenate the resulting Strings and wrap them in triple backticks with the language set to verilog:

```scala
class MyModule extends RawModule {
  val in = IO(Input(UInt(8.W)))
  val out = IO(Output(UInt(8.W)))
  out := in + 1.U
}
```
```verilog
module MyModule(
  input  [7:0] in,
  output [7:0] out
);
  assign out = in + 8'h1; // @[main.scala 9:13]
endmodule
```

Note that imports are okay in mdoc:verilog blocks, but any utility Scala code should be in a separate block.