Wie kann ich doctest mit Beispielen in Markdown-Codeblöcken für mkdocs ausführen? ⇐ Python

[Anonymous]

Ich verwende mkdocs und mkdocstring, um meine Dokumentation zu erstellen und Codebeispiele in die Dokumentzeichenfolgen aufzunehmen. Ich verwende auch doctest (über pytest --doctest-modules), um alle diese Beispiele zu testen.
Option 1 – Format für Dokumentation
Wenn ich meinen Dokumentstring so formatiere:

Code: Select all

    """
Recursively flattens a nested iterable (including strings!) and returns all elements in order left to right.

Examples:
--------
```
>>> [x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
```
"""

Dann wird es in der Dokumentation gut dargestellt, aber doctest schlägt mit dem folgenden Fehler fehl:

Code: Select all

Expected:
[1, 2, 3, 4, 5, 6, 7, 8, 9]
```
Got:
[1, 2, 3, 4, 5, 6, 7, 8, 9]

Das macht Sinn, da doctest alles behandelt, bis eine Leerzeile wie erwartet ausgegeben wird und darauf abzielt, genau
Option 2 – Format für doctest
Wenn ich den Docstring für doctest ohne Codeblöcke formatiere:

Code: Select all

    """
Recursively flattens a nested iterable (including strings!) and returns all elements in order left to right.

Examples:
--------
>>> [x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
"""

dann ist doctest erfolgreich, aber die Dokumentation wird gerendert



[x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])][1, 2, 3, 4, 5, 6, 7, 8, 9]



Workaround? - Fügen Sie eine Leerzeile für doctest hinzu
Wenn ich es mit einer zusätzlichen Leerzeile vor dem Ende des Codeblocks formatiere:

Code: Select all

    """
Recursively flattens a nested iterable (including strings!) and returns all elements in order left to right.

Examples:
--------
```
>>> [x for x in flatten([1,2,[3,4,[5],6],7,[8,9]])]
[1, 2, 3, 4, 5, 6, 7, 8, 9]

```
"""

Dann besteht doctest den Test, aber

• am Ende des Beispiels in der Dokumentation befindet sich eine Leerzeile (hässlich)
• Ich muss daran denken, am Ende jedes Beispiels eine Leerzeile einzufügen (fehleranfällig und nervig)

Kennt jemand eine bessere Lösung?