Documentation refresh/fixups

Refresh the documentation and fix possible mistakes to make it ready for KF6.

• remove old documentation examples and replace them with the current implementation
• specify code highlighting
• add deprecation warning to code that might get removed in KF6
• add links to HIG and to the kirigami tutorial
• reword descriptions