From f40144dc27e7c100240e503952b7c09c62d3b26f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Cramfox=E2=80=9D?= <“kasey@n0.computer”>
Date: Fri, 6 Dec 2024 17:37:36 -0500
Subject: [PATCH] add "Getting Started" section to the README and add the
 readme to the docs

---
 README.md  | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/lib.rs |  1 +
 2 files changed, 55 insertions(+)

diff --git a/README.md b/README.md
index 8867860..b6b7ce9 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,60 @@ the whole store with all replicas to a single file.
 
 [paper]: https://arxiv.org/abs/2212.13567
 
+# Getting Started
+
+The entry into the `iroh-docs` protocol is the `Docs` struct, which uses an [`Engine`](https://docs.rs/iroh-docs/latest/iroh_docs/engine/struct.Engine.html) to power the protocol.
+
+`Docs` was designed to be used in conjunction with `iroh`. [Iroh](https://docs.rs/iroh) is a networking library for making direct connections, these connections are peers send sync messages and transfer data.
+
+Iroh provides a [`Router`](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html) that takes an [`Endpoint`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html) and any protocols needed for the application. Similar to a router in webserver library, it runs a loop accepting incoming connections and routes them to the specific protocol handler, based on `ALPN`.
+
+`Docs` is a "meta protocol" that relies on the [`iroh-blobs`](https://docs.rs/iroh-blobs) and [`iroh-gossip`](https://docs.rs/iroh-gossip) protocols. Setting up `Docs` will require setting up `Blobs` and `Gossip` as well.
+
+Here is a basic example of how to set up `iroh-docs` with `iroh`:
+
+```rust
+use iroh::{protocol::Router, Endpoint};
+use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool, ALPN as BLOBS_ALPN};
+use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN};
+use iroh_docs::{protocol::Docs, ALPN as DOCS_ALPN};
+
+#[tokio::main]
+async fn main() -> Result<(), std::fmt::Error> {
+    // create an iroh endpoint that includes the standard discovery mechanisms
+    // we've built at number0
+    let endpoint = Endpoint::builder().discovery_n0().bind().await.unwrap();
+
+    // create a router builder, we will add the
+    // protocols to this builder and then spawn
+    // the router
+    let builder = Router::builder(endpoint);
+
+    // build the blobs protocol
+    let local_pool = LocalPool::default();
+    let blobs = Blobs::memory().build(local_pool.handle(), builder.endpoint());
+
+    // build the gossip protocol
+    let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await.unwrap();
+
+    // build the docs protocol
+    let docs = Docs::memory().spawn(blobs.clone(), gossip.clone()).await.unwrap();
+
+    // setup router
+    let router = builder
+        .accept(BLOBS_ALPN, blobs)
+        .accept(GOSSIP_ALPN, gossip))
+        .accept(DOCS_ALPN, docs.clone())
+        .spawn()
+        .await
+        .unwrap();
+
+    // do fun stuff with docs!
+
+    Ok(())
+}
+  
+```
 
 # License
 
diff --git a/src/lib.rs b/src/lib.rs
index f5ee94d..e4dc865 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 //! Multi-dimensional key-value documents with an efficient synchronization protocol
 //!
 //! The crate operates on [Replicas](Replica). A replica contains an unlimited number of