Issues

Issue #169 resolved

strip doctest comments in rendered output

Chad Dombrova
created an issue

it is common to use special doctest comments such as

{{{

foo() #doctest: +SKIP }}}

to control how doctest blocks are interpreted during testing, however, they should not appear in rendered html/latex/etc output as it might confuse readers and adds clutter to the examples.

Comments (8)

  1. Georg Brandl repo owner

    I just saw that I had already implemented this, for the doctest directive in the doctest extension. I think that if you want this, you can as well use ".. doctest::" to make it obvious. Do you agree?

  2. Chad Dombrova reporter

    correct me if i'm wrong here, but i thought the doctest directive only covered doctests using this format:

    .. doctest::
    
       foo()
    

    and not implicit doctests:

    >>> foo()
    

    the patch i added fixes the latter case. perhaps there is a more elegant solution?

  3. Georg Brandl repo owner

    That is true (except that you need the ">>>" for the first one too).

    But I would argue that if you want special processing, you could use the directive.

  4. Chad Dombrova reporter

    if we can agree that doctest comments should be stripped when using the doctest directive, then shouldn't the same logic apply to the implicit doctests? to put it another way, what would be the argument for keeping them in one and not in the other? in what case does the user desire to see his doctest comments in html output (other than the obviously esoteric case of demonstrating how to use doctest comments)?

    on a side note, seems as though the implicit syntax should just run the default doctest directive mechanism, so that it's just a subset of the same case, but i'm not terribly well-versed in the docutils api, so perhaps this redirection is not so easy.

  5. Log in to comment