Improve cargo docs

[cargopete]

Improve docs that are automatically generated by cargo doc. This includes:

1. Add more information and examples (real code snippets that can compile from the docs themselves)
2. Improve structure
3. Add link to Docs portal and emphasise that it's our central "source of truth"