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?)

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

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).

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...