diff options
| -rw-r--r-- | document_tree/Cargo.toml | 10 | ||||
| -rw-r--r-- | document_tree/README.md | 49 | ||||
| -rw-r--r-- | document_tree/src/lib.rs | 9 | ||||
| -rw-r--r-- | parser/Cargo.toml | 5 | ||||
| -rw-r--r-- | parser/README.md | 9 | ||||
| -rw-r--r-- | renderer/Cargo.toml | 5 | ||||
| -rw-r--r-- | renderer/README.md | 16 | ||||
| -rw-r--r-- | rst/Cargo.toml | 5 | ||||
| -rw-r--r-- | rst/README.md | 16 |
9 files changed, 112 insertions, 12 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() ]); diff --git a/parser/Cargo.toml b/parser/Cargo.toml index a423fbe..f208f22 100644 --- a/parser/Cargo.toml +++ b/parser/Cargo.toml @@ -5,10 +5,11 @@ authors = ['Philipp A. <flying-sheep@web.de>'] edition = '2018' description = 'a reStructuredText parser' license = 'MIT OR Apache-2.0' +readme = 'README.md' -documentation = 'https://flying-sheep.github.io/rust-rst' +documentation = 'https://docs.rs/rst_parser' homepage = 'https://github.com/flying-sheep/rust-rst' -repository = 'https://github.com/flying-sheep/rust-rst.git' +repository = 'https://github.com/flying-sheep/rust-rst' [dependencies] document_tree = { path = '../document_tree', version = '0.3.0' } diff --git a/parser/README.md b/parser/README.md new file mode 100644 index 0000000..81d3d16 --- /dev/null +++ b/parser/README.md @@ -0,0 +1,9 @@ +`rst_parser` +============ + +Part of the [`rst`][rst] crate family. +Offers the functions `parse` and `parse_only`, +which try to create a `document_tree::Document`. +`parse` simplifies this document and resolves references before returning it. + +[rst]: https://github.com/flying-sheep/rust-rst/#readme diff --git a/renderer/Cargo.toml b/renderer/Cargo.toml index c53c53f..051d175 100644 --- a/renderer/Cargo.toml +++ b/renderer/Cargo.toml @@ -5,10 +5,11 @@ authors = ['Philipp A. <flying-sheep@web.de>'] edition = '2018' description = 'a reStructuredText renderer' license = 'MIT OR Apache-2.0' +readme = 'README.md' -documentation = 'https://flying-sheep.github.io/rust-rst' +documentation = 'https://docs.rs/rst_renderer' homepage = 'https://github.com/flying-sheep/rust-rst' -repository = 'https://github.com/flying-sheep/rust-rst.git' +repository = 'https://github.com/flying-sheep/rust-rst' [dependencies] document_tree = { path = '../document_tree', version = '0.3.0' } diff --git a/renderer/README.md b/renderer/README.md new file mode 100644 index 0000000..69aa1ec --- /dev/null +++ b/renderer/README.md @@ -0,0 +1,16 @@ +`rst_renderer` +============== + +Part of the [`rst`][rst] crate family. +This crate contains the HTML renderer (which supports most of what the parser supports), +as well as the broken XML and JSON renderers. +Suggestions and PRs welcome on how to get them right! + +```rust +let document = Document::with_children(vec![...]); // or rst_parser::parse() +let stream = std::io::stdout(); +let standalone = true; // wrap in <!doctype html><html></html> +render_html(document, stream, standalone); +``` + +[rst]: https://github.com/flying-sheep/rust-rst/#readme diff --git a/rst/Cargo.toml b/rst/Cargo.toml index 3c58792..a0a288e 100644 --- a/rst/Cargo.toml +++ b/rst/Cargo.toml @@ -5,10 +5,11 @@ authors = ['Philipp A. <flying-sheep@web.de>'] edition = '2018' description = 'a reStructuredText parser and renderer for the command line' license = 'MIT OR Apache-2.0' +readme = 'README.md' -documentation = 'https://flying-sheep.github.io/rust-rst' +documentation = 'https://github.com/flying-sheep/rust-rst#readme' homepage = 'https://github.com/flying-sheep/rust-rst' -repository = 'https://github.com/flying-sheep/rust-rst.git' +repository = 'https://github.com/flying-sheep/rust-rst' [dependencies] rst_renderer = { path = '../renderer', version = '0.3.0' } diff --git a/rst/README.md b/rst/README.md new file mode 100644 index 0000000..9abd297 --- /dev/null +++ b/rst/README.md @@ -0,0 +1,16 @@ +`rst` +===== + +Part of The [`rst`][rst] crate family. +This crate contains the CLI: + +```bash +cargo install rst +rst README.rst +# or +cargo run -- README.rst +``` + +Maybe it will also contain a library with convenience reexports of the data structure, parser, and renderer. + +[rst]: https://github.com/flying-sheep/rust-rst/#readme |