Python

1929 readers

1 users here now

A community for talking about the Python programming language.

founded 1 year ago

MODERATORS

[email protected]

Testable examples with MkDocs (self.python)

submitted 1 year ago by Glitterkoe to c/[email protected]

1 comments fedilink hide all child comments

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?

top 1 comments

sorted by: hot top controversial new old

[–] Glitterkoe 1 points 1 year ago* (last edited 1 year ago)

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.