DRIVERS-3010 reformat specs for improved mkdocs rendering (#1678)

* mdformat: bump mdformat to version 0.7.18
* mdformat: add mdformat-mkdocs plugin (enforcing 4-space indent)
* mkdocs: add superfences extension, to fix indented fenced code
* mkdocs: add arithmatex (and MathJax) for math mode support
* mkdocs: add escapeall extension to fix rendering of escaped angle brackets
* mkdocs: enable markdown footnote support
* mkdocs: add extra.css rules to improve table and list readability
* ci: git diff when pre-commit fails, so that mdformat disagreements are visible in the log
* readme: suggest installing dependencies from requirements.txt
* tag all fenced code blocks with a language (mkdocs leaves hljs configured to guess a language, not leave untagged code unformatted)
* use code blocks for code more, especially to avoid unintended math mode
* convert remaining unclosed div elements to closed span
* additional manual indentation fixes

Author: Micah Scott @ MongoDB

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,6 +6,6 @@ Please complete the following before merging:
 - [ ] Make sure there are generated JSON files from the YAML test files.
 - [ ] Test changes in at least one language driver.
 - [ ] Test these changes against all server versions and topologies (including standalone, replica set, sharded
-  clusters, and serverless).
+    clusters, and serverless).
 
 <!-- See also: https://wiki.corp.mongodb.com/pages/viewpage.action?pageId=80806719 -->

.github/workflows/lint.yml

@@ -17,7 +17,7 @@ jobs:
       - name: "Run pre-commit"
         run: |
           pip install -U -q pre-commit
-          pre-commit run --all-files --hook-stage manual
+          pre-commit run --all-files --hook-stage manual || (git diff; false)
 
   mkdocs:
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -23,12 +23,16 @@ repos:
       stages: [manual]
 
 - repo: https://github.com/executablebooks/mdformat
-  rev: 0.7.17
+  rev: 0.7.18
   hooks:
     - id: mdformat
       args: ["--wrap=120", "--number"]
       additional_dependencies:
-        [mdformat-gfm, mdformat-frontmatter, mdformat-footnote, mdformat-gfm-alerts]
+        - mdformat-footnote
+        - mdformat-frontmatter
+        - mdformat-gfm
+        - mdformat-gfm-alerts
+        - mdformat-mkdocs~=3.0
 
 - repo: local
   hooks:

LICENSE.md

@@ -46,10 +46,11 @@ entire test with a note (e.g. *Removed*).
 
 ## Building Documents
 
-We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run:
+We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, in a
+Python [venv](https://docs.python.org/3/library/venv.html) run:
 
 ```bash
-pip install mkdocs
+pip install -r source/requirements.txt
 mkdocs serve
 ```
 

README.md

@@ -4,11 +4,19 @@ nav:
   - 'index.md'
 markdown_extensions:
   - admonition
+  - footnotes
+  - pymdownx.superfences
+  - pymdownx.arithmatex
+  - pymdownx.escapeall
   - toc:
       permalink: 
 plugins:
   - gh-admonitions
 validation:
   absolute_links: warn 
   unrecognized_links: warn
-  anchors: warn
+  anchors: warn
+extra_javascript:
+  - 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS_CHTML'
+extra_css:
+  - extra.css

mkdocs.yml

@@ -31,7 +31,7 @@ python3 scripts/migrate_to_md.py "source/<path_to_rst_file>"
 - Ensure that the generated markdown file is properly formatted.
 
 - Ensure that the links in the new file are working, by running `pre-commit run markdown-link-check` and addressing
-  failures until that passes.
+    failures until that passes.
 
 - Remove the rst file using `git rm`.
 

scripts/README.md

@@ -67,4 +67,4 @@ configuration and execute a ping command. Repeat this test using SCRAM-SHA-256.
 - 2022-10-05: Add spec front matter
 
 - 2020-07-15: Link to CRUD test runner implementation and note that the collection under test must not be dropped before
-  each test.
+    each test.