Docs: refresh the page about the eDSL

[anshumanmohan]

After #1894 has landed, I'd like to take locks and revise the eDSL docs. Here is a non-exhaustive list:

• I'm finding the introductory example a little confusing. I think it should be smaller and should also show the .futil code it generates.
• I think we should advertise the "grab a handle as you define it" style upfront instead of leaving it as a "trick + tip". Consequently, get_cell, get_group, and get_component can be pushed down to the tricks and tips section.
• Some other tricks and tips are lacking motivation and examples.
• The docs have nothing about the new static stuff!
• The docs are far behind when it comes to the new higher-level constructs, like <op>_use, if_with, and while_with.

[sampsyo]

All these proposals sound great.

[anshumanmohan]

I am finally getting back to this, and am planning a bigger overhaul than previously outlined. There are actually two pages of documentation:

1. Emitting Calyx from Python, which walks through builder_example.py and also discusses a tiny made-up code snippet to show parallelism in the control section.
2. Builder Library Reference, which presents a multi-component design as an example and then covers a number of topics.

Let us say that the things that these two pages cover are our "syllabus", and we won't drop anything from the syllabus without talking about it. As I mentioned above, neither of these pages discusses static stuff or the new higher-level constructors, so that stuff goes into the syllabus too.

I propose to overhaul/extend builder_example.py, such that the documentation of the builder library can mostly "just" be a discussion of the example program, and such that that discussion covers the syllabus.

I want to teach people using a runnable example because many of the builder's features (especially the "modern" higher-level constructors) can only be understood via code generation: a single line of Python generates quite a few lines of Calyx in different parts of the Calyx program. This is why just showing snippets of Python/Calyx is ineffective.

I want the example program to show most features, but I don't want to overwhelm the user with too much info at once. To this end, I'm going to split the builder example into a number of components. A component will have a small number of self-contained lessons.

Here's the syllabus:

• Adding a component
• Adding input and output ports
• Adding registers
• Adding computational units like adders
• Adding a group using the with {component}.group("group_name") as group_handle: syntax
• Adding a group with a static delay -- outdated?
• Adding a combinational group, and what that is for
• Writing to ports using dot notation
• Width inference of constants
• Guarded assignments
• "Bare names" -- I need a motivating example
• Continuous assignments
• Accessing a component's ports while defining it using this
• Control operators: seq, par, if, while, invoke
• Building and emitting programs to Calyx
• Multi-component designs
• 1-d memories, and reading and writing to them
• Marking memories as external or "by reference"
• Retrieving handles to components, cells, groups by name -- will cover this entirely in the doc. My plan is to write out the Python code to define component mux, but by using a bunch of these handle-retrieving methods.
• Defining component attributes -- I need a motivating example.
• High and low signals, and using them
• Static timing -- will cover entirely in the doc. I'll just point out that the adder component has latency one, and show the Python code to generate the static annotation.
• Higher-level constructs, like <op>_use, if_with, and while_with.

[anshumanmohan]

I have pushed the beginnings of this new example. So far I have the following components:

• adder: Teaches how to add components, ports, cells. Shows how to define a group in the verbose manner. Shows dot notation to access ports. Shows the HI signal shorthand. Shows how to continuously output an answer. Shows how to access a port of a component that is under construction.
• abs_diff: Shows off a higher-order construct that does reg := a-b in one line of Python. Shows a more complicated control, with an if check. Uses a ge check that is written in a verbose way, using a group and not a comb group. Shows how to create a comb group for an lt check as a one-liner. Shows a higher-order if_with construct in the control; this works with the one-liner lt check by not unwrapping a tuple of cell and comb group.
• mux: Shows a multi-component design.

[anshumanmohan]

I have now pushed two further components:

• map: Covers 1d memory, items passed by reference, while loops, width inference, guarded assignments, and the higher-order helper incr.
• main: Covers external memories and invocations.

[anshumanmohan]

I am close to done when it comes to new code, so I welcome your feedback on that! Please see #2002 for the code that I've been writing. In some cases I have annotated the syllabus above to ask for help or guidance.