python: doctest my github-markdown files?

Question

I'd like to run the doctests from this file, and it's not clear to me out to accomplish it:

README.md:

# WELCOME!

This library is helpful and will help you in _many_ ways!

For example:

```
>>> import library
>>> library.helps()
True
```

(aside: can anyone help me get this to highlight as markdown?)

Datolite

Answer 1

As an alternative to doctest I wrote mkcodes, a script that pulls code blocks out of markdown files so they can be tested in a separate file.

Here's my actual test script using mkcodes:

mkcodes --github --output tests/docs/test_{name}.py docs
py.test tests
pyflakes tests
pep8 tests

Parliamentarian

Answer 2

You can run doctest on your README on the command line using:

python -m doctest -v README.md

The -m parameter tells Python to run the following module as a script. When run as a script, the doctest module runs the doctest.testmod function on the following file. Lastly, the -v parameter makes doctest run in verbose mode; if it's turned off, doctest only produces output if at least one test fails (and will produce no output if everything is successful).

Rampageous

Updating the code may easily make the documentation examples wrong. The test suite should / will tell us when this happens. – Datolite

Completely sure is preferable to pretty sure. – Datolite

@Datolite Hey, I just got a notification for this answer. I'm not sure why I was so snarky when I originally wrote it. Sorry about that. I just updated my answer to (hopefully) be more helpful/informative. – Rampageous

This doesn't work with Markdown's fenced code blocks because the ”closing fence” is considered as part of the output/result by the doctest module and generates one failure per block. – Aporia

Answer 3

Just found this phmdoctest package which seems to work fine with common python highlighting markdown:

Any text here for example...
```python
print(1+2)
```
sample output:
```
3
```

and a simple usage:

phmdoctest README.md --outfile tests/test_readme.py
python -m pytest tests -v

in the first line, you generate a new test file and later just run stand testing for whole your project...

Schoonmaker

Answer 4

I am the author/owner of phmdoctest mentioned above.

Edit the original question README.md and make sure the fence code blocks you want tested begin with

```python

Then run

phmutest README.md --replmode --log

phmutest

phmutest compared to phmdoctest has these new features:

• Tests all FCBs in the Markdown file as a single example.
• Runs tests internally with Python standard library test runners.
• Caller can provide their own Python initialization and cleanup code.
• Callable from a pytest test case.
• A single example can extend across files.

Erato