Set up mdformat to format documentation

[fyliu]

Overview

Since we're using markdown for documentation, we should set up a formatter to fix any simple problems. mdformat seem to be the best option available for now.

Action Items

• [x] set up mdformat in pre-commit

Resources/Instructions

• mdformat-mkdocs code block indent issue

[fyliu]

I was going to include it in #166 but the software has a problem that needs to be fixed first. I linked to the issue in resources. The author said he won't be able to work on it until next week.

[fyliu]

It also doesn't support the pymdownx.tabbed syntax extension that I'm using through material for mkdocs.

The syntax is essentially

1. starts with '=== "tab title"' (variations: ===+, ===!)
2. tab content is indented (4 spaces)
3. end when "something else" starts at the starting indent level

An example from the above docs

=== "Tab 1"
    Markdown **content**.

    Multiple paragraphs.

=== "Tab 2"
    More Markdown **content**.

    - list item a
    - list item b

It looks like there's a similar mdformat plugin called mdformat-admon that we can adapt if necessary. But this is now something that'll take a little extra effort either from a kind outside developer or ourselves before we can add it to pre-commit.

[fyliu]

In the meantime, we can use mdformat manually and just accept the well-formatted parts. Install it locally in a pipx environment with the helpful plugins:

pipx install mdformat
pipx inject mdformat mdformat-admon mdformat-mkdocs

Run it against files

mdformat docs/how-to/add-models-and-api-endpoints.md

Stage any useful formatting and commit:

git add -p
git commit

[fyliu]

Good news! The mdformat-mkdocs developer fixed the bug (in v1.1.2) and also implemented support for Content Tabs formatting (in v2.0.0) I mentioned above. This should support all the markdown extension constructs I'm planning on using.

Now I'm waiting for him to tag the v2.0.0 release so it pushes to pypi where we can use it in pre-commit. It's already in the main branch there.

Here's are the work branches:

• add-mdformat works with the v1.1.2 fix. So I will use it to close this issue.
• convert-mkdocs is waiting on v2.0.0 . It contains docs changes that's really part of #167, so I will open the PR for this branch there.

[KyleKing]

It also doesn't support the pymdownx.tabbed syntax extension that I'm using through material for mkdocs.

The syntax is essentially

1. starts with '=== "tab title"' (variations: ===+, ===!)

I wasn't aware of the optional ! and +. I'll make an update to include those and should have a release later today (https://github.com/KyleKing/mdformat-mkdocs/issues/17)

[KyleKing]

Update: mdformat-mkdocs v2.0.0rc3 was just released has a minor fix for a formatting edge case and expanded support for ===! and ===+ content tabs!

Update: v2.0.1 is now available!