feat: Remove Share struct, add documentation, add rc constructor variants

[appcypher]

Summary

This PR adds and updates existing documentation, doc tests and makes other API clean ups.

• Add more information to docs home page
• Remove unused types and Share struct
• Update READMEs
• Add rc constructor variants

Test plan (required)

• Testing the code.

  scripts/wnfs.sh test

Closing issues

[codecov]

Codecov Report

Merging #343 (549cec6) into main (2d15fbd) will decrease coverage by 0.25%.
The diff coverage is 36.66%.

@@            Coverage Diff             @@
##             main     #343      +/-   ##
==========================================
- Coverage   57.08%   56.83%   -0.25%     
==========================================
  Files          45       45              
  Lines        3346     3336      -10     
  Branches      836      833       -3     
==========================================
- Hits         1910     1896      -14     
- Misses        874      883       +9     
+ Partials      562      557       -5     

Files Changed	Coverage Δ
wnfs-common/src/metadata.rs	24.52% <ø> (ø)
wnfs/examples/file_variants.rs	0.00% <0.00%> (ø)
wnfs/examples/mnemonic_based.rs	0.00% <0.00%> (ø)
wnfs/examples/private.rs	0.00% <0.00%> (ø)
wnfs/examples/public.rs	0.00% <0.00%> (ø)
wnfs/examples/tiered_blockstores.rs	0.00% <0.00%> (ø)
wnfs/examples/write_proofs.rs	0.00% <0.00%> (ø)
wnfs/src/lib.rs	90.00% <ø> (ø)
wnfs/src/private/file.rs	73.39% <0.00%> (-2.22%)	⬇️
wnfs/src/private/forest/traits.rs	100.00% <ø> (ø)
... and 11 more

... and 1 file with indirect coverage changes

[matheus23]

Big fan of most changes, just not a big fan of saving a bunch of characters with the rc name.
Wdyt about new_rc? Or perhaps an rc function with the signature fn rc(self) -> Rc<Self>? So it's &mut PrivateDirectory::new(...).rc() (perhaps that's too easy to miss in examples though)?

[appcypher]

Or perhaps an rc function with the signature fn rc(self) -> Rc? So it's &mut PrivateDirectory::new(...).rc() (perhaps that's too easy to miss in examples though)?

Thought about making an rc function; probably should go with that.
I know this change adds little but I think it simplifies the interface makes it less verbose. We almost always wrap these types in Rcs; they have little use outside of that so I think it only makes sense to make it part of the API.
Also, it is in line with functions like Box::pin that wraps a Box in Pin. There are similar functions like this in the ecosystem.

[matheus23]

Also, it is in line with functions like Box::pin that wraps a Box in Pin. There are similar functions like this in the ecosystem.

hmm I see. I'd argue Box is just inherently a simpler type (& Box::new thus a simpler function), since it's just a wrapper.
The constructor for PrivateDirectory::new takes multiple arguments and is more complex than a wrapper.

What do you think of calling the function new_rc?

Also. Perhaps worth trying this out: How crazy would it be if new simply always returned an Rc? Do we have code in rs-wnfs that would break? Maybe we can base our whole API around Rc<PrivateDirectory> and &mut Rc<PrivateDirectory>...

[matheus23]

Addresses some of the #315

[appcypher]

@matheus23 Thanks for fixing 👍. Was going to get to it today.