docs: Auto-format markdown documentation

This patch uses mdformat to auto-format markdown documentation.

To support \ for line breaks (which is what mdformat uses), mkdocs now
requires the pymdownx.escapeall extension.

Because of incompatibilities between mdformat (which formats to
CommonMark) and mkdocs (which expects Python-Markdown), there are now
some limitations: no nested lists, multi-paragraph list items, or
admonitions support.

These limitations are acceptable for now, although some of the docs had
to be adjusted to meet them.

.mkdocs.yml

@@ -14,6 +14,8 @@ markdown_extensions:
       guess_lang: false
   - attr_list
   - admonition
+  - pymdownx.escapeall:
+      hardbreak: true
 
 theme: readthedocs