merge libmaple docs ("leaflabs-docs") into ./docs

In the past, libample documentation was forked out of this repository
because the documentation had increased in scope. For the librambutan,
and the rambutan project in general, we will try to keep documentation
closer to the source code, so the librambutan-specific documentation
should live here. Other sections of leaflabs-docs will be culled in a
following commit.

This merge attempts to maintain history by using a subtree strategy.
Followed directions at:

    http://nuclearsquid.com/writings/subtree-merging-and-you/

Full history for files should be accessible using the "--follow" flag to
git log, eg:

    git log --follow docs/source/adc.rst

It should be possible to pull patches from leaflabs-docs with:

    git pull -s subtree leaflabs-docs master

... at least until the docs in this repository diverge significantly.

1 files changed, 71 insertions, 0 deletions

diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst
new file mode 100644
index 0000000..9875ee6
--- /dev/null
+++ b/docs/source/lang/api/random.rst
@@ -0,0 +1,71 @@
+.. highlight:: cpp
+
+.. _lang-random:
+
+random()
+========
+
+The ``random()`` function generates pseudo-random numbers.
+
+Library Documentation
+---------------------
+
+.. FIXME [Breathe] use doxygenfunction when possible
+
+.. cpp:function:: random(long max)
+
+   Same as a call to ``random(0, max)``.
+
+.. cpp:function:: random(long min, long max)
+
+   Generate a pseudo-random number with given lower and upper bounds.
+
+   *Parameters*
+
+   - ``min`` - Lower bound on the returned value, inclusive
+   - ``max`` - Upper bound on the returned value, exclusive
+
+   *Returns*: A pseudo-random number in the range [min, max).
+
+Discussion
+----------
+
+If it is important for a sequence of values generated by
+:ref:`random() <lang-random>` to differ, on subsequent executions of a
+sketch, use :ref:`randomSeed() <lang-randomseed>` to initialize the
+random number generator with a fairly random input, such as
+:ref:`analogRead() <lang-analogread>` on an unconnected pin.
+
+Conversely, it can occasionally be useful to use pseudorandom
+sequences that repeat exactly. This can be accomplished by calling
+``randomSeed()`` with a fixed number, before starting the random
+sequence.
+
+Example
+-------
+
+The following sketch initializes the random seed based on an :ref:`ADC
+<adc>` reading of pin 0.  If this pin is unconnected, the Sketch
+should print different values to the :ref:`serial monitor
+<ide-serial-monitor>` each time it is run::
+
+    long randNumber;
+
+    void setup() {
+      pinMode(0, INPUT_ANALOG);
+      randomSeed(analogRead(0));
+    }
+
+    void loop() {
+      randNumber = random(300);
+      SerialUSB.println(randNumber);
+
+      delay(50);
+    }
+
+See Also
+--------
+
+-  :ref:`randomSeed() <lang-randomseed>`
+
+.. include:: /arduino-cc-attribution.txt