Doctests are interpreted by the HTML template

[mikael-s]

When producing the output in HTML mode, doctests are simply interpreted as if they were part of markdown syntax and are replaced by (three) blockquotes.

For instance if you have the following code in a test.py file:

def f():
    '''
    >>> f()
    2
    '''
    return 2

Launching pdoc on that file with pdoc --html test.py will produce a HTML file where the docstring is replaced by the following code:

<blockquote>
<blockquote>
<blockquote>
<p>f()
2</p>
</blockquote>
</blockquote>
</blockquote>

Therefore the >>> are removed and the line return is ignored which makes the doctests hardly readable.

[peterjc]

I would retitle this slightly, but can confirm that pdoc does not nicely render docstests in docstrings. Example:

from __future__ import print_function

def double(x):
   """Return double the input value.

   >>> double(5)
   10
   >>> double(1.25)
   2.5

   """
   return x * 2

if __name__ == "__main__":
    for v in [0.1, 3, 123]:
        print("Doubling %r gives %r" % (v, double(v)))

Then

$ pdoc --version
0.3.2
$ pdoc --html example.py 
$ open example.m.html

Gives:

...
  <section id="section-items">

    <h2 class="section-title" id="header-functions">Functions</h2>
      
  <div class="item">
    <div class="name def" id="example.double">
    <p>def <span class="ident">double</span>(</p><p>x)</p>
    </div>
    

    
  
    <div class="desc"><p>Return double the input value.</p>
<blockquote>
<blockquote>
<blockquote>
<p>double(5)
10
double(1.25)
2.5</p>
</blockquote>
</blockquote>
</blockquote></div>
  <div class="source_cont">
...

[peterjc]

This seems to be a limitation of the markdown rendering engine - which makes sense after all, >>> is not part of the Markdown language.

If pdoc supported reStructuredText as input, that does include support for >>> doctests - see #111.

[cortesi]

Please see #153 for a unified discussion ticket about docstring flavors.

[jpc]

For anyone who stumbled upon this issue. It does work well now but you need to make sure to keep the indentation on the doctest part be the same as on the docstring text.

In other words this works:

    """
    Example:
    >>> print(5)
    """

this does not:

    """
    Example:
        >>> print(5)
    """