[WIP] 📝 Flesh out documentation and examples.

[hayleigh-dot-dev]

• [x] Complete, runnable example in README.md.
• [x] Tiny crash-course on what ANSI escape sequences are/do.
• [x] Table of contents to logically organise module functions.
• [x] Minimal complete example for every text format function.
• [x] Minimal complete example for every text colour function.
  • [x] Regular colours (black/white/red/...)
  • [x] Bright variants (bright_black, ...)
  • [x] pink (The example output should show the right escape code, but I wasn't sure of the format.)
  • [x] rgb8
  • [x] rgb24
• [x] Minimal complete example for every background colour function.

---

You'll realise that the doc comments for most of these functions are identical to one-another, so what is the point? If a user is linked to a particular function in the docs (or they're looking in there editor), we don't want them to have to scroll around to find an example that looks like the thing they want. Instead, I think, we should include an immediately-relevant example with every function.

[hayleigh-dot-dev]

As an aside, I wish languages had a better way of authoring documentation besides co-locating it with the source. +900 lines of docs for functions that are mostly one line 😅

[brettkolodny]

And 90% of which are for colours I can not personally see. Writing good documentation is truly altruistic

[brettkolodny]

I finished adding the missing docs but the styling is weird because certain styles can overlap and others can't. It may be helpful to make a table to explain this. It's also somewhat hard to test because it's dependent on what is supported on any given terminal.

[hayleigh-dot-dev]

Incredible! I couldn't find a resource online that explained which styles could overlap and which couldn't, and I don't personally know. I think the docs are probably Good Enough, fortunately publishing docs and publishing the package are separate so we can always iterate on docs once we're happy we have a good base and the API is stable enough.

---

It's also somewhat hard to test because it's dependent on what is supported on any given terminal.

We can deal with tests in another PR (I think simply testing the text output is correct wrt escape codes is sufficient)