Migrate use case docs into Sphinx

[gnidan]

• Start with pandoc-converted RST file
• Add Solidity extensions to project for highlighting
• Update all code examples, either:
  • Directly referencing file in repo via literalinclude directive
  • Providing necessary preprocessing command whose output is pasted into RST source
• Replace *<glossary-term>* with glossary reference.
• Remove use cases from README.md

ℹ️ Preview

[njgheorghita]

Other than a couple typos that we might as well iron out here - looks great. Though, personally the use cases are much too wordy/difficult to parse for my liking. We have two descriptors for a use case-

1. actual package name - i.e. owned - short & succinct but not descriptive
2. use case def - i.e. Package with a contract with link dependencies on a contract from a package dependency - descriptive but long and difficult to parse mentally

I think it'd be great if we could either improve (i.e. shorten but maintain descriptiveness) 2. defs - or come up with something in-between 1. and 2. Though, i'm certain once we get plantuml visuals in here - those will do a lot to help cut through the wordiness of it all.

[gnidan]

Thanks @njgheorghita @pipermerriam

Piper– I opened an issue for updating the packages. I figure we'll do that once this spec is more finalized for v2.

[gnidan]

Ah @njgheorghita re your other point:

Other than a couple typos that we might as well iron out here - looks great. Though, personally the use cases are much too wordy/difficult to parse for my liking. We have two descriptors for a use case-

1. actual package name - i.e. owned - short & succinct but not descriptive
2. use case def - i.e. Package with a contract with link dependencies on a contract from a package dependency - descriptive but long and difficult to parse mentally

I think it'd be great if we could either improve (i.e. shorten but maintain descriptiveness) 2. defs - or come up with something in-between 1. and 2. Though, i'm certain once we get plantuml visuals in here - those will do a lot to help cut through the wordiness of it all.

This is valid, and I was a bit frustrated by the lack of clarity myself. I'll fix that up in another PR.