docs: add "Getting Started" section to the README and add the readme …

…to the docs (#19)

Co-authored-by: “ramfox” <“kasey@n0.computer”>
Co-authored-by: Ruediger Klaehn <rklaehn@protonmail.com>

README.md

@@ -29,6 +29,57 @@ 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_docs::{protocol::Docs, ALPN as DOCS_ALPN};
+use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // create an iroh endpoint that includes the standard discovery mechanisms
+    // we've built at number0
+    let endpoint = Endpoint::builder().discovery_n0().bind().await?;
+
+    // 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?;
+
+    // build the docs protocol
+    let docs = Docs::memory().spawn(&blobs, &gossip).await?;
+
+    // setup router
+    let router = builder
+        .accept(BLOBS_ALPN, blobs)
+        .accept(GOSSIP_ALPN, gossip)
+        .accept(DOCS_ALPN, docs)
+        .spawn()
+        .await?;
+
+    // do fun stuff with docs!
+    Ok(())
+}
+```
 
 # License
 

deny.toml

@@ -34,6 +34,7 @@ license-files = [
 ignore = [
       "RUSTSEC-2024-0370", # unmaintained, no upgrade available
       "RUSTSEC-2024-0384", # unmaintained, no upgrade available
+      "RUSTSEC-2024-0421", # todo: remove when iroh gets updated
 ]
 
 [sources]

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