Split microrm documentation out into separate README.

microrm/README.md

@@ -0,0 +1,58 @@
+`microrm` is a crate providing a lightweight ORM on top of SQLite.
+
+Unlike fancier ORM systems, microrm is intended to be extremely lightweight
+and code-light, which means that by necessity it is opinionated, and thus
+lacks the power and flexibility of, say, SeaORM or Diesel. In particular,
+`microrm` currently makes no attempts to provide database migration support.
+
+`microrm` provides two components: modeling and querying. The intention is
+that the modelling is built statically; dynamic models are not directly
+supported though are possible. However, since by design microrm does not
+touch database contents for tables not defined in its model, using raw SQL
+for any needed dynamic components may be a better choice.
+
+Querying supports a small subset of SQL expressed as type composition.
+
+A simple example using an SQLite table as an (indexed) key/value store
+might look something like this:
+```rust
+use microrm::{Entity,make_index};
+#[derive(Debug,Entity,serde::Serialize,serde::Deserialize)]
+pub struct KVStore {
+    pub key: String,
+    pub value: String
+}
+
+// the !KVStoreIndex here means a type representing a unique index named KVStoreIndex
+make_index!(!KVStoreIndex, KVStoreColumns::Key);
+
+let schema = microrm::model::SchemaModel::new()
+    .add::<KVStore>()
+    .index::<KVStoreIndex>();
+
+// dump the schema in case you want to inspect it manually
+for create_sql in schema.create() {
+    println!("{};", create_sql);
+}
+
+let db = microrm::DB::new_in_memory(schema).unwrap();
+let qi = db.query_interface();
+
+qi.add(&KVStore {
+    key: "a_key".to_string(),
+    value: "a_value".to_string()
+});
+
+// because KVStoreIndex indexes key, this is a logarithmic lookup
+let qr = qi.get_one_by(KVStoreColumns::Key, "a_key");
+
+assert_eq!(qr.is_some(), true);
+assert_eq!(qr.as_ref().unwrap().key, "a_key");
+assert_eq!(qr.as_ref().unwrap().value, "a_value");
+```
+
+The schema output from the loop is (details subject to change based on internals):
+```sql
+CREATE TABLE IF NOT EXISTS "kv_store" (id integer primary key,"key" text,"value" text);
+CREATE UNIQUE INDEX "kv_store_index" ON "kv_store" ("key");
+```

microrm/src/lib.rs

@@ -1,62 +1,4 @@
-//! `microrm` is a crate providing a lightweight ORM on top of SQLite.
-//!
-//! Unlike fancier ORM systems, microrm is intended to be extremely lightweight
-//! and code-light, which means that by necessity it is opinionated, and thus
-//! lacks the power and flexibility of, say, SeaORM or Diesel. In particular,
-//! `microrm` currently makes no attempts to provide database migration support.
-//!
-//! `microrm` provides two components: modeling and querying. The intention is
-//! that the modelling is built statically; dynamic models are not directly
-//! supported though are possible. However, since by design microrm does not
-//! touch database contents for tables not defined in its model, using raw SQL
-//! for any needed dynamic components may be a better choice.
-//!
-//! Querying supports a small subset of SQL expressed as type composition.
-//!
-//! A simple example using an SQLite table as an (indexed) key/value store
-//! might look something like this:
-//! ```rust
-//! use microrm::{Entity,make_index};
-//! #[derive(Debug,Entity,serde::Serialize,serde::Deserialize)]
-//! pub struct KVStore {
-//!     pub key: String,
-//!     pub value: String
-//! }
-//!
-//! // the !KVStoreIndex here means a type representing a unique index named KVStoreIndex
-//! make_index!(!KVStoreIndex, KVStoreColumns::Key);
-//!
-//! let schema = microrm::model::SchemaModel::new()
-//!     .add::<KVStore>()
-//!     .index::<KVStoreIndex>();
-//!
-//! // dump the schema in case you want to inspect it manually
-//! for create_sql in schema.create() {
-//!     println!("{};", create_sql);
-//! }
-//!
-//! let db = microrm::DB::new_in_memory(schema).unwrap();
-//! let qi = db.query_interface();
-//!
-//! qi.add(&KVStore {
-//!     key: "a_key".to_string(),
-//!     value: "a_value".to_string()
-//! });
-//!
-//! // because KVStoreIndex indexes key, this is a logarithmic lookup
-//! let qr = qi.get_one_by(KVStoreColumns::Key, "a_key");
-//!
-//! assert_eq!(qr.is_some(), true);
-//! assert_eq!(qr.as_ref().unwrap().key, "a_key");
-//! assert_eq!(qr.as_ref().unwrap().value, "a_value");
-//! ```
-//!
-//! The schema output from the loop is (details subject to change based on internals):
-//! ```sql
-//! CREATE TABLE IF NOT EXISTS "kv_store" (id integer primary key,"key" text,"value" text);
-//! CREATE UNIQUE INDEX "kv_store_index" ON "kv_store" ("key");
-//! ```
-
+#![doc = include_str!("../README.md")]
 
 mod meta;
 pub mod model;
@@ -285,8 +227,7 @@ mod test {
 
 #[cfg(test)]
 mod test2 {
-    use crate::{Entity,make_index};
-    #[derive(Debug,Entity,serde::Serialize,serde::Deserialize)]
+    #[derive(Debug,crate::Entity,serde::Serialize,serde::Deserialize)]
     #[microrm_internal]
     pub struct KVStore {
         pub key: String,