docs: Documentation updates

[pawamoy]

Meta issue for tracking documentation improvements.

• [ ] limitation with footnotes, references (see https://github.com/mkdocstrings/pytkdocs/issues/26)
• [ ] how to document enumeration values
• [ ] recommendation: giving a heading to each object, even modules
• [ ] suggest https://github.com/analog-garage/mkdocstrings-python-xref as alternate handler with relative cross-refs
• [ ] suggest https://github.com/jcayers20/mkdocs-autoapi for automatic generation of pages (see https://github.com/mkdocstrings/mkdocstrings/issues/389)
• [ ] see all issues with docs label