More readthedocs documentation

Author: toroidal-code

docs/index.md

@@ -6,7 +6,14 @@ C++Spec is a behavior-driven development library with an RSpec-inspired DSL.
 
 ## Overview ##
 
+C++Spec is a behavior-driven development library for C++ with an RSpec-inspired DSL. Designed with ease of use and rapid prototyping in mind, C++Spec offers an alternative to traditional testing libraries and frameworks.
+
+Also see the [official GitHub pages site](http://toroidal-code.github.io/cppspec/) for more 
+information.
 
 ## Installing ##
 
+Either run `git clone https://github.com/toroidal-code/cppspec.git` or download the collated header
+file (if it is available). You can also download a ZIP version of the repo.
 
+If you want to manually generate the collated `cppspec.hpp`, you can download the ccollate tool [here](https://raw.githubusercontent.com/toroidal-code/ccollate/master/ccollate.rb) and then run `./ccollate.rb` in the toplevel directory of the C++Spec repo.

docs/syntax/expect.md

@@ -0,0 +1,43 @@
+# Expect
+
+Expectations are the primary focus of C++Spec, allowing clean, readable tests without falling
+back on assertions.
+
+Expectations have two parts, the "actual" value, and the "expected" value.
+
+```c++
+auto x = 2;
+expect(x).to_equal(2);
+//     ^           ^
+//	actual      expected
+```
+
+The `expect` half references whatever is being tested (the "actual" result of the test), while the
+matcher references what the value _should_ be (the "expected" value of the test).
+
+## Values
+
+The standard usage of an `expect` is to reference a variable or value to test.
+
+```c++
+Something some_thing();
+
+expect(some_thing.some_method()).to_be_true();
+```
+
+## Lambdas
+
+Expectations are also to contain lambdas that return objects or throw exceptions.
+
+```c++
+expect([] { return 2; }).to_equal(2);
+expect([] { throw std::exception; }).to_throw<std::exception>();
+```
+
+This allows creating delayed "thunks" that can be created earlier and then passed to the 
+`Expectation`.
+
+```c++
+auto val = [] { return 5; };
+expect(val).to_equal(5);
+```

docs/syntax/it.md

@@ -1,2 +1,30 @@
 # It
 `it`s are the examples of the spec. A `Description` holds a group of `it`s, where each `it` has at least one expectation.
+
+An `it` has the form of
+
+```c++
+it("description string", _ {...})
+```
+
+An `it` can also have an implicit description that is generated by the contained expectation
+
+```c++
+it(_{...})
+```
+
+!!! important
+
+    Take note of the `_`. This is used whenever you write an `it`, similar to `$` for `describe`.
+
+
+Each `it` is run as part of the containing parent `Description`, whether that be the toplevel
+`describe` or an `explain`.
+
+So for example,
+
+```c++
+describe an_example_it("An example of an it", $ {
+	it("looks like this", {...});
+});
+```

docs/syntax/let.md

@@ -0,0 +1,23 @@
+
+# Let
+
+A `let` introduces a memoized local variable inside of a `Description`. This is best shown in an
+example:
+
+```c++
+int _count = 0;
+describe let_spec("let", $ {
+  let(count, [&]{ return ++_count ;});
+
+  it("memoizes the value", _ {
+    expect(count).to_equal(1);
+    expect(count).to_equal(1);
+  });
+
+  it("is not cached across examples", _ {
+    expect(count).to_equal(2);
+  });
+});
+```
+
+As shown, `let`s allow setting a mutating variable before each `it`.