Python @sh.itjust.works Glitterkoe @lemmy.world 1y ago

Testable examples with MkDocs

Hey there!

I'm looking to move my documentation over to MkDocs (+Material Theme), but I'm struggling to integrate testable code examples. Does anyone have a workflow for this?

Main requirements:

Testable. Want to make sure my examples work as intended.
Continuable code fences (i.e. some regular Markdown in between chunks of code)

Nice-to-have:

Formatting
Output checking (otherwise, regular asserts will do)

I would have thought Python to have near first-class support for this, but there doesn't seem to be a clear winner as far as plugins go.

Any ideas?

1 comments

By now, the pymdownx.snippets extension that retrieves sections from plain pytest Python files seems to be my way to go. Tests run code as always, which is also formatted as always, specifically marked sections end up in docs. Win, win, win by grace of the scissors operator.