WIP

docs/Makefile

@@ -7,18 +7,15 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
-EXAMPLES      = $(wildcard ../examples/*.vir)
+EXAMPLES      = $(wildcard sources/examples/*.vir)
 
 
 auto: Makefile examples $(EXAMPLES) # rustdocs
-	mkdir -p ./source/examples/
-	cp ../examples/*.vir ./source/examples/
 	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: auto clean examples push rustdocs
 
 clean:
-	rm -rf ./source/examples
 	rm -rf $(BUILDDIR)
 	rm -rf ./latexbuild/
 

docs/source/_static/custom.css

@@ -6,3 +6,25 @@
 .wy-side-nav-search {
     background-color: #167d60;
 }
+
+/*********************************************************************************/
+/*
+    Style the :caption: on a .. code-block:: directive.
+*/
+/*********************************************************************************/
+
+.caption-text {
+    font-style: normal;
+}
+
+.rst-content .code-block-caption {
+    padding: 0.5em 0.7em;
+    border: 1px solid #e1e4e5;
+    border-bottom: none;
+    background: #d9d9d9;
+    text-align: left;
+}
+
+.rst-content div {
+    margin-top: 0 !important;
+}

docs/source/getting-started.rst

@@ -2,14 +2,27 @@ Getting Started
 ===============
 
 Tradition dictates that the first program that is written in any programming language should be Hello, World!
-In that same spirit, let's look at the "hello world" of Virdant: `Passthrough`:
+In that spirit, in hardware languages, we write a design which blinks an LED on and off.
+So let's make an LED blink by writing the "hello world" of Virdant:
 
-.. literalinclude:: examples/passthrough.vir
+.. literalinclude:: examples/blink.vir
+   :caption: blink.vir
    :language: virdant
    :linenos:
 
-We see a module declaration, `mod Passthrough`.
-Inside, we see two ports, one `incoming` port named `out` and one `outgoing` port named `in`.
-Both have type `Word[8]`, meaning that an 8-bit value passes across them.
-The line `out := in` connects the input port `in` to the output port `out`.
-The notation `:=` is called a wire.
+We see a module declaration, `mod Blink`.
+Inside, we see two ports, one `implicit` port named `clock` and one `outgoing` port named `led`.
+The first port, `clock` has type `Clock`, and so it gives the circuit its pulse.
+It is an implicit clock, so it is automatically fed to all `reg`\s which need a clock.
+The second port, `led`, will represent the state of our LED.
+When it's `true`, the LED is on, and when it's `false`, the LED is off.
+
+The next line declares a `reg` called `led_on` with type `Bit`.
+A `reg` is a hardware register.
+It is a memory cell in our design.
+The next line after that is a driver statement.
+It tells us that every clock cycle, the value of `led_on` becomes `len_on->not()`.
+In other words, it flips from `true` to `false` or `false` to `true` on every clock cycle.
+
+The last line of the module, `led := led_on` is another driver statement.
+It drives `led` continuously to have the same value as the current value of `led_on`.

docs/source/modules.rst

@@ -6,16 +6,23 @@ Module Definitions
 ------------------
 Modules are declared using the `mod` keyword.
 
-A module has a list of pins, a list of components, and a list of wires.
+Modules consist of a list of statements.
+These do things like:
+
+* declare ports to allow the module to communicate with the outside world
+* declare registers for tracking the state of the module
+* instantiate submodules
+* perform logic
 
 The following example is a `Buffer` module, which demonstrates all three parts:
 
 .. literalinclude:: examples/buffer.vir
+   :caption: buffer.vir
    :language: virdant
    :linenos:
 
 This module has two ports, an incoming port `in` and and outgoing port `out`.
-Both carry a value of type `Word[1]` (that is, a bit) to and from the module.
+Both carry a value of type `Word[8]` -- a byte -- to and from the module.
 
 This module contains one subcomponent: a `reg` (register) named `queue`.
 It stores a value of type `Word[1]`.