Have Pycco recognize doctests as code?

Question

Is there any way to have Pycco recognize doctests as code and render them appropriately?

E.g. the docstring of the following function

def fib(i):
    """ Fibonacci number

    >>> fib(10)
    55
    """
    if i < 2:
        return i
    else:
        return fib(i-1) + fib(i-2)

Renders In Pycco like the following

Fibonacci number

           fib(10) 5

Clearly the >>> was interpretted as indentation and code highlighting did not take effect. This seems like a common use case. is there a plugin somewhere that I'm missing?

Looking at the code, comments are processed by markdown, so the `>>>` prompt is interpreted as the start of a quote section. If you want more formatting options, you might have to look elsewhere; `sphinx` is the canonical choice, and does support doctests (see e.g. http://sphinx-doc.org/ext/doctest.html). — jonrsharpe, Jan 05 '15 at 22:56
Yeah, I'm aware. I was hoping that this might be special cased in some plugin somewhere due to it's prevalence. — MRocklin, Jan 05 '15 at 23:27
FWIW, doctests are convenient when you're using CPython exclusively, but if you introduce Pypy, Jython or IronPython (or a different version of CPython...), doctests can be a hindrance. — dstromberg, Jan 05 '15 at 23:31

score 1 · Answer 1 · answered Jan 06 '15 at 22:17

Python doesn't mind if the doctest suite is indented an additional four characters compared to the rest of the docstring, as long as it's internally consistent, so the following will pass the tests just fine (tested in 2.7.9 and 3.4.2):

def test():
    """Doctest test

    The following are doctests:

        >>> test()
        'foo'

    That went well.

    """
    return 'foo'

if __name__ == "__main__":
    import doctest
    doctest.testmod(verbose=True)

This additional indentation will be interpreted as a code block by pycco, just as it is in the Markdown here on SO. The above test renders in HTML as follows:

Screen grab of rendered pycco HTML

Have Pycco recognize doctests as code?

1 Answers1