Added READMEs

3 files changed, 62 insertions, 6 deletions

diff --git a/document_tree/Cargo.toml b/document_tree/Cargo.toml
index afbce73..9e1c481 100644
--- a/document_tree/Cargo.toml
+++ b/document_tree/Cargo.toml
@@ -2,14 +2,14 @@
 name = 'document_tree'
 version = '0.3.0'
 authors = ['Philipp A. <flying-sheep@web.de>']
-description = 'reStructuredText’s DocumenTree representation'
+edition = '2018'
+description = 'reStructuredText’s DocumentTree representation'
 license = 'MIT OR Apache-2.0'
+readme = 'README.md'
 
-documentation = 'https://flying-sheep.github.io/rust-rst'
+documentation = 'https://docs.rs/document_tree'
 homepage = 'https://github.com/flying-sheep/rust-rst'
-repository = 'https://github.com/flying-sheep/rust-rst.git'
-
-edition = '2018'
+repository = 'https://github.com/flying-sheep/rust-rst'
 
 [dependencies]
 failure = '0.1.6'
diff --git a/document_tree/README.md b/document_tree/README.md
new file mode 100644
index 0000000..a6acb9c
--- /dev/null
+++ b/document_tree/README.md
@@ -0,0 +1,49 @@
+`document_tree`
+===============
+
+Part of the [`rst`][rst] crate family.
+This crate contains structs and traits mirroring [Docutils’ Document Tree][doctree] model.
+The basic structure is a tree of [elements][], some of which [have children][] and/or [extra attributes][].
+
+```rust
+use document_tree::*;
+use document_tree::{extra_attributes as a, element_categories as c, attribute_types as t};
+
+#[test]
+fn imperative() {
+    let mut doc = Document::default();
+    let mut title = Title::default();
+    let url = "https://example.com/image.jpg".parse().unwrap();
+    let image = ImageInline::with_extra(a::ImageInline::new(url));
+    title.append_child("Hi");
+    title.append_child(image);
+    doc.append_child(title);
+    println!("{:?}", doc);
+}
+
+#[test]
+fn descriptive() {
+    let doc = Document::with_children(vec![
+        Title::with_children(vec![
+            "Hi".into(),
+            ImageInline::with_extra(a::ImageInline::new(
+                "https://example.com/image.jpg".parse().unwrap()
+            )).into(),
+        ]).into()
+    ]);
+    println!("{:?}", doc);
+}
+```
+
+Check out the other crates in the family on how to create one from rST markup or render it!
+
+The advantages of this approach are that it’s convenient to have the children interface,
+as well as to trivially map elements to XML.
+The disadvantage is that a “vector of children” is not a well-defined model for the more structured elements
+like e.g. a section, which always contains a title followed by blocks.
+
+[rst]: https://github.com/flying-sheep/rust-rst/#readme
+[doctree]: https://docutils.sourceforge.io/docs/ref/doctree.html
+[elements]: https://docs.rs/document_tree/0/document_tree/elements/trait.Element.html
+[have children]: https://docs.rs/document_tree/0/document_tree/element_categories/trait.HasChildren.html
+[extra attributes]: https://docs.rs/document_tree/0/document_tree/extra_attributes/trait.ExtraAttributes.html
diff --git a/document_tree/src/lib.rs b/document_tree/src/lib.rs
index 324fc44..9154725 100644
--- a/document_tree/src/lib.rs
+++ b/document_tree/src/lib.rs
@@ -19,12 +19,16 @@ pub use self::element_categories::HasChildren;
 #[cfg(test)]
 mod tests {
 	use super::*;
+	use std::default::Default;
 
 	#[test]
 	fn imperative() {
 		let mut doc = Document::default();
 		let mut title = Title::default();
+		let url = "https://example.com/image.jpg".parse().unwrap();
+		let image = ImageInline::with_extra(extra_attributes::ImageInline::new(url));
 		title.append_child("Hi");
+		title.append_child(image);
 		doc.append_child(title);
 
 		println!("{:?}", doc);
@@ -34,7 +38,10 @@ mod tests {
 	fn descriptive() {
 		let doc = Document::with_children(vec![
 			Title::with_children(vec![
-				"Hi".into()
+				"Hi".into(),
+				ImageInline::with_extra(extra_attributes::ImageInline::new(
+					"https://example.com/image.jpg".parse().unwrap()
+				)).into(),
 			]).into()
 		]);