Am 02.02.2015 um 18:42 schrieb Colin Macdonald:
I've recently learned how to use address@hidden to put the expected result
into the texinfo docs of my functions. (Thanks to "interval" pkg dev!)
Is there any existing way to run these as tests? Like doctest in
Python? I.e., extract them, run them, make sure the output matches the
address@hidden The documentation refers to "example" but that seems to
pull in `%!demo` blocks instead.
The @result{} is just a macro that produces the ⇒ symbol in the
documentation. I find it useful for short examples in the documentation.
I copy the console output into the @example, replacing “$variable = ”
with the macro.
As a package maintainer I prefer to have these examples as test cases,
just to make sure that the documentation is correct. That's why I like
your proposal. The simplest solution IMHO is to add a %!test block for
examples used in the documentation manually.
It is complicated to check the @examples automatically, you must consider:
- The @example blocks must not follow any particular syntax, nor must
they contain useful code,
- the author of the example blocks may have abreviated commands or
console output,
- if you wanted to check the console output of the examples, you would
have to intercept the stdout,
- some results may be system-dependent,
- …
I expect the answer will be "no, but please write such a thing"... :(
I'd find it useful to code simple %!test blocks, which will be used to
generate additional @example blocks at the end of the documentation.
Perhaps introduce a new %!example block?! However, automating this is
probably not worth it, since this only makes sense for short code
snippets and the examples in the documentation usually do not change often.
infsup_doctests.log