Document watch and upcoming changes

[cben]

Turns out watch was barely documented, while it very much needs documentation 😁
Preparation for 5.0 changes proposed in #275 (comment)

Also, the whole "Examples" section (which is really the main documentation) is messy, took a small step towards organizing it...

@grosser @qingling128 @mszabo @Stono please review

[cben]

• In several places here, I neglected to say which exception / how exactly to detect 410 errors. I don't really want people to now write code catching HTTP errors and to check notice.code, I hope to fix them asap (and I intend to have a separate sub-exception for 410 because of its importance).

• I didn't mention the new "BOOKMARK" type.
  Kubeclient doesn't know how to opt-in yet. Once we track last seen version, we could opt-in and honor these transparently without yielding them to the block. Will decide how to cross that bridge when we get there.
  I wondered if I should add generic advice to ignore unknown type for future compatibility? But if people did that now, we'd all be ignoring "type": "ERROR" 😆 And it seems k8s will make any new types opt-in.

[cben]

BTW, the terminology "watch notice" comes from Kubeclient::WatchNotice, which we dropped in #299. The k8s golang & opeapi type name is WatchEvent, so maybe should start using that?
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#watchevent-v1-meta

[mszabo]

lgtm