diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a041e59..14e6634 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,9 @@ Don't use glob imports, even for preludes. Sort imports. +Examples should be simple and obvious enough that an experienced dev +won't need comments. Explanation should be in prose. + Describe the code in prose, not in comments. Things that should be described include any traits imported and their methods used. Think about what information here supports the use case and might not be diff --git a/README.md b/README.md index 853f4ab..c65267d 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,26 @@ -# Cookin' with Rust +# A Rust Cookbook -A practical guide to the Rust crate ecosystem. +**[Read it here]**. -## Recipes -### [Byteorder](src/pages/byteorder.md) [![byteorder][byteorder-badge]][byteorder] -### [File IO](src/pages/file_io.md) [![file][file-badge]][file] -### [Command Line Parsing](src/pages/cliparsing.md) [![clap][clap-badge]][clap] -### [JSON](src/pages/json.md) [![json][json-badge]][json] -### [TOML](src/pages/toml.md) [![toml][toml-badge]][toml] -### [rand](src/pages/rand.md) [![rand][rand-badge]][rand] -### [rayon](src/pages/rayon.md) [![rayon][rayon-badge]][rayon] +This _Rust Cookbook_ is a collection of simple examples that +demonstrate good practices to accomplish common programming tasks, +using the crates of the Rust ecosystem. + +These examples are complete, and suitable for copying directly into +new cargo projects. They are tested and guaranteed to work. + +[Read it here]: https://brson.github.io/rust-cookbook ## Contributing -If you'd like to make changes to the project, please see [this guide](CONTRIBUTING.md). + +This project is intented to be easy for new Rust programmers to +contribute to, and an easy to way get involved with the Rust +community. It needs and welcomes help. + +For details see [CONTRIBUTING.md] on GitHub. + +[CONTRIBUTING.md]: https://github.com/brson/rust-cookbook/blob/master/CONTRIBUTING.md ## License MIT/Apache-2.0 - - - - -[byteorder-badge]: https://img.shields.io/crates/v/byteorder.svg?label=byteorder -[byteorder]: https://docs.rs/byteorder -[file-badge]: https://img.shields.io/crates/v/file.svg?label=file -[file]: https://doc.rust-lang.org/std/fs/struct.File.html -[clap-badge]: https://img.shields.io/crates/v/clap.svg?label=clap -[clap]: https://kbknapp.github.io/clap-rs/clap/struct.Arg.html -[json-badge]: https://img.shields.io/crates/v/json.svg?label=json -[json]: http://json.rs/doc/json -[toml-badge]: https://img.shields.io/crates/v/toml.svg?label=toml -[toml]: http://alexcrichton.com/toml-rs/toml/ -[rand-badge]: https://img.shields.io/crates/v/rand.svg?label=rand -[rand]: https://doc.rust-lang.org/rand/rand/index.html -[error-docs]: https://doc.rust-lang.org/book/error-handling.html -[error-blog]: https://brson.github.io/2016/11/30/starting-with-error-chain -[rayon-badge]: https://img.shields.io/crates/v/rayon.svg?label=rayon -[rayon]: https://doc.rust-lang.org/rayon/rayon/index.html diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8f9a784..e86e597 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,6 +1,7 @@ # Summary [Table of Contents](intro.md) +[About](about.md) [A Note About Error Handling](error_handling_note.md) - [Basics](basics.md) diff --git a/src/error_handling_note.md b/src/about.md similarity index 94% rename from src/error_handling_note.md rename to src/about.md index ccc0e73..75795b4 100644 --- a/src/error_handling_note.md +++ b/src/about.md @@ -1,4 +1,12 @@ -# A note about error handling +# About "Cookin' with Rust" + +## Who this book is for + +## How to read this book + +## How to use the examples + +## A note about error handling Error handling in Rust is robust when done correctly, but in today's Rust it requires a fair bit of boilerplate. Because of this one often @@ -89,4 +97,3 @@ Rust book][error-docs] and [this blog post][error-blog]. [error-docs]: https://doc.rust-lang.org/book/error-handling.html [error-blog]: https://brson.github.io/2016/11/30/starting-with-error-chain - diff --git a/src/intro.md b/src/intro.md index e6e874f..e5ed7ee 100644 --- a/src/intro.md +++ b/src/intro.md @@ -2,11 +2,24 @@ A practical guide to the Rust crate ecosystem. +This _Rust Cookbook_ (a.k.a. _Cookin' with Rust_), is a collection of +simple examples that demonstrate good practices to accomplish common +programming tasks, using the crates of the Rust ecosystem. +[Read more about _Cookin' with Rust_](about.html), including tips for +how to read the book, how to use the examples, notes on conventions. -## Recipes +## Contributing -### Basics +This project is intented to be easy for new Rust programmers to +contribute to, and an easy to way get involved with the Rust +community. It needs and welcomes help. + +For details see [CONTRIBUTING.md] on GitHub. + +[CONTRIBUTING.md]: https://github.com/brson/rust-cookbook/blob/master/CONTRIBUTING.md + +## Basics | Recipe | Crates | Categories | |--------|--------|------------| @@ -16,36 +29,25 @@ A practical guide to the Rust crate ecosystem. | [Generate random values on a custom type][ex-rand-custom] | [![rand-badge]][rand] | [![cat-math-badge]][cat-math] | | [Construct a graph of objects][ex-petgraph-basic] | [![petgraph-badge]][petgraph] | [![cat-math-badge]][cat-math] | -### Serialization +## Serialization | Recipe | Crates | Categories | |--------|--------|------------| | [Serialize and deserialize unstructured JSON][ex-json-basic] | [![json-badge]][json] | [![cat-serialization-badge]][cat-serialization] | | [Deserialize an unstructured TOML configuration file][ex-toml-basic] | [![toml-badge]][toml] | [![cat-serialization-badge]][cat-serialization] | -### Concurrency +## Concurrency | Recipe | Crates | Categories | |--------|--------|------------| | [Mutate the elements of an array in parallel][ex-rayon-iter-mut] | [![rayon-badge]][rayon] | [![cat-concurrency-badge]][cat-concurrency] | -### Application development +## Application development | Recipe | Crates | Categories | |--------|--------|------------| | [Parse command line arguments][ex-clap-basic] | [![clap-badge]][clap] | [![cat-app-badge]][cat-app] | -## Contributing - -If you'd like to make changes to the project, please see [this guide](pages/contributing.html). - -## License - -MIT/Apache-2.0 - - - -