Merge pull request #3 from Thorium/add-some-docs

Documentation update

Author: Thorium

README.md

@@ -1,6 +1,10 @@
 # FSharp.Control.R3
 
-Extensions and wrappers for using R3 with F#.
+Extensions and wrappers for using [R3](https://github.com/Cysharp/R3) with F#.
+
+
+[Documentation](https://fsprojects.github.io/FSharp.Control.R3/)
+
 
 ---
 

docsSrc/Explanations/Background.md

@@ -7,4 +7,16 @@ index: 1
 
 # Background
 
-Here's a core concept and reasons why this exists at a deeper level.
+`IObservable<T>` is .NET way of dealing with lazy event streams with publish/subscribe-pattern called Reactive Programming, "LINQ to Events and async operations".
+
+Where a standard list (IEnumerable) is pull-based, IObservable is a push-based (infinite) list, like "a lazy list of mouse events": when an event happens, the corresponding list gets a new value.
+If Nullable is just "a list of 0 or 1", then async-await could be just an IObservable of 0 or 1.
+
+There are many advantages of using reactive programming and Rx:
+  - Manual thread/lock -handling can be avoided
+  - No temporary class variables to capture the current or some previous state 
+  - Testing is easy: generate lists like they would be event-lists. 
+  - Testing the wrong async event order is easy. 
+  - Also, testing long-duration workflows is easy as you can "fake" time passing
+
+It's always good to have alternatives, and if R3 is your alternative to Rx, then `FSharp.Control.R3` is your F# wrapper, like `FSharp.Control.Reactive` F#.

docsSrc/How_Tos/Doing_A_Thing.md

@@ -7,3 +7,8 @@ index: 1
 
 # How To do a first thing
 
+The best way to use IObservable is to use one .Subscribe()-method which will take function parameters (which will be "injected" to the right place).
+
+Use Rx (or R3) when you need async events to communicate with each other, e.g.:
+-  Events, WebServices, Threads, Timers, AutoComplete, Drag & Drop, ...
+

docsSrc/Tutorials/Getting_Started.md

@@ -7,16 +7,51 @@ index: 1
 
 # Getting Started
 
+To use the raw R3 from F# you would add first the NuGet package to R3:
+
+    [lang=bash]
+    paket install R3
+
+Then, this is a working sample:
+
 ```fsharp
-open FSharp.Control.R3
-let foo = ()
-let myAge = 21
-let color = Say.FavoriteColor.Red
+open System
+
+// Create a bus
+use r3Bus = new R3.Subject<int> ()
+
+// Filter events
+let interesting = R3.ObservableExtensions.Where (r3Bus, fun x -> x % 2 = 0)
+
+// Subscribe to events
+let subscription =
+    R3.ObservableExtensions.SubscribeAwait (
+        interesting,
+        fun i cancellationToken ->
+            task {
+                // Listen events
+                printfn "%i" i
+                return ()
+            }
+            |> System.Threading.Tasks.ValueTask
+    )
+
+// Publish some events
+[ 1..10 ] |> List.iter r3Bus.OnNext
 ```
 
-## Here is the path to downloading
+As you can see, this is nice, but a little bit noisy.
+This package will come top help.
+
+Then you do:
 
     [lang=bash]
     paket install FSharp.Control.R3
 
+Now you have available functions like:
 
+```fsharp
+open FSharp.Control.R3.Async
+
+Observable.length r3Bus
+```

docsSrc/index.md

@@ -2,16 +2,28 @@
 
 ---
 
-## What is FSharp.Control.R3?
+FSharp.Control.R3 provides F#-style modules for working with the [R3](https://github.com/Cysharp/R3).
 
-FSharp.Control.R3 is a library that does this specific thing.  
+The fundamental problem with AsyncSeq is that the subscriber cannot say, "I've had enough; unsubscribe me, please".
 
-## Why use FSharp.Control.R3?
+The solution for this is [Reactive Extensions (Rx)](https://github.com/dotnet/reactive), which has an F# wrapper [FSharp.Control.Reactive](https://fsprojects.github.io/FSharp.Control.Reactive/).
 
-I created it because I had to solve an issue with this other thing.
+R3 is a similar wrapper for [R3](https://github.com/Cysharp/R3), a re-implementation of Rx.
 
 ---
 
+<div class="row">
+  <div class="span1"></div>
+  <div class="span6">
+    <div class="well well-small" id="nuget">
+      The FSharp.Control.R3 library can be <a href="https://nuget.org/packages/FSharp.Control.R3">installed from NuGet</a>:
+      <pre>PM> Install-Package FSharp.Control.R3</pre>
+    </div>
+  </div>
+  <div class="span1"></div>
+</div>
+
+
 <div class="row row-cols-1 row-cols-md-2">
   <div class="col mb-4">
     <div class="card h-100">