refactor: examples

[0xMelkor]

Motivation

The examples directory is the first place for developers to onboard quickly on ethers-rs. Anyway the lack of a proper structure makes it difficult to find useful content.

Solution

I catched your desire to provide something similar to this ebook repo and started restructuring the entire folder providing:

1. ToC README in the root dir
2. Refactor examples by topic
3. Provide new examples where missing
4. In another PR create a CI step to export docs in convenient formats

I'll leave this in DRAFT till completion of the first 3 points.
@gakonst @mattsse @prestwich let me know if the ToC is missing some core topics.

Thank you guys

PR Checklist

• Added Tests
• Added Documentation
• Updated the changelog
• Breaking changes

[gakonst]

Absolutely love this. Strong yes, and we can use the feature checklist as a roadmap.

[DaniPopes]

This is amazing, thanks for taking this on!

Some early notes:

• I think it might make more sense if the READMEs contained only a few or no examples, leaving the job to the individual files to avoid having to maintain the same code twice and risking having the examples in the README be out of date.
• If a type implements a trait in std::{cmp, ops} (which is the case for U256), you can write the expression using the regular operator and you also won't need to bring the trait into scope (this is true only for the traits that are not already in scope from the prelude). This is explained in more detail in the std::ops docs. Example:

- use std::ops::Add;
let a = U256::from(100);
let b = U256::from(100);
- assert!(a.eq(&b));
- assert_eq!(a.add(&b), U256::from(200));
+ assert_eq!(a, b); // = assert!(a == b)
+ assert_eq!(a + b, U256::from(200));

[gakonst]

gg this is a great start excited for when it lands

[gakonst]

This is great. Love the new format. Let's make sure we can run the tests in CI, else can merge.

[0xMelkor]

Hi guys,
we are almost there, but I need to solve some points before merge:

• Read RPC_URL from env
• Update ToC
• All examples are built with default features => update CI to provide special features if required

Most of READMEs in example crates are empty. Should we merge leaving them open for contribs?
Thanks!

[gakonst]

Sounds good to me on all fronts! Thanks for taking this on.

[DaniPopes]

nits

I think we can also remove the prefix on example files:

- examples/big-numbers/examples/bn_conversion.rs
+ examples/big-numbers/examples/conversion.rs

[0xMelkor]

nits

I think we can also remove the prefix on example files:

- examples/big-numbers/examples/bn_conversion.rs
+ examples/big-numbers/examples/conversion.rs

Removed all prefixes. I also ensured that no broken references were left.

[mattsse]

awesome

[gakonst]

full send - nice work. we should take some time to write the book now :D cc @0xKitsune see these new examples

[0xKitsune]

Awesome, thanks for the heads up. I'll check these out later today.

[0xMelkor]

Hi guys, how should we contrib the book?

• I saw @0xKitsune provided a repo here.
• Other guys suggested to inline the examples in the rust docs using nightly docs features
• Other ideas..

@gakonst @0xKitsune

[gakonst]

I'd love to put stuff in the repo so PRs etc are merged in lockstep. I also want to respect Kit wanting to have their own repo, so I don't mind fragmentation of effort, although I'd obviously prefer if we made a new docs/book-type folder here and went ham there. I don't mind if it's an mdbook or the nightly thing.

Andrea if you want to take point for the docs in this repo go for it, and we'll figure it out with @0xKitsune

[0xKitsune]

I also want to respect Kit wanting to have their own repo, so I don't mind fragmentation of effort, although I'd obviously prefer if we made a new docs/book-type folder here and went ham there. I don't mind if it's an mdbook or the nightly thing.

As usual, I would be more than happy to combine efforts and work on the book/docs here. I made the Tour-of-ethers-rs repo before I knew that the official book was going to be developed. I was originally planning on writing something that walked through each part of the lib with examples along the way, kind of like the Rust Book (but a little less text heavy). Im definitely open to brainstorming on what the most effective resource might look like, feel free to add me to any conversations.

[gakonst]

Sick - if you're down to combine then let's do it