@example's as doctests

classic Classic list List threaded Threaded
29 messages Options
12
Reply | Threaded
Open this post in threaded view
|

@example's as doctests

Colin Macdonald
Hi all,

I've recently learned how to use `@result{}` 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
`@result{}`...  The documentation refers to "example" but that seems to
pull in `%!demo` blocks instead.

I expect the answer will be "no, but please write such a thing"... :(

thanks,
Colin

--
Colin Macdonald
Associate Professor
Tutorial Fellow at Oriel College
University of Oxford


signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
Am 02.02.2015 um 18:42 schrieb Colin Macdonald:
> I've recently learned how to use `@result{}` 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
> `@result{}`...  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.

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
On 02/02/15 18:23, Oliver Heimlich wrote:
> 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.

Right.  But then I have to keep them in sync :(  Worse, I'll have to
check that contributors' patches do that too.

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

Within any one (smallish or new) project, those are not too big a problem.

>  - if you wanted to check the console output of the examples, you would
> have to intercept the stdout,
>  - some results may be system-dependent,

Good points.  Some of them are are solvable within any particular
toolbox.  Things like system-dependent or otherwise varying inputs are
usually flaggable as such (i.e., in Python doctest).

I've taken a look at doctest-for-matlab which I'll post about in a new
thread.

best,
Colin


signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
In reply to this post by Oliver Heimlich
Oliver (and octave-maintainers),

I've hacked doctest-for-matlab enough [1] to run it on the infsup class
from your Interval package.  Interval uses the standard Octave @result{}
convention: in my patched version, I split on @result{} and some other
heuristics.  It could be improved, see last bullet below.

[1] https://github.com/catch22/doctest-for-matlab/pull/10

I attach a log: most tests pass.  Oliver: I'm impressed!

I noticed:
   * there are a few actual errors.
   * there are some cases of @example used as a LaTeX alternative
     (is there an @verbatim instead?)
   * there a few minor (cosmetic?) errors: [-1, 5] to [-1, +5]
   * there are a couple cases were my current splitting
     input/output based on @result{} fails.  (Personally I prefer
     marking input with ">>" but the doctest code could instead be
     refactored further.)

Finally. I checked several functions in core: spdiags and svd are fairly
close to testable.  qr, chol not really written with this sort of tool
in mind.  IIRC, others warned me this was true of core Octave.

Colin

On 02/02/15 18:23, Oliver Heimlich wrote:

> Am 02.02.2015 um 18:42 schrieb Colin Macdonald:
>> I've recently learned how to use `@result{}` 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
>> `@result{}`...  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 (8K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
Am 27.03.2015 um 10:39 schrieb Colin Macdonald:

> Oliver (and octave-maintainers),
>
> I've hacked doctest-for-matlab enough [1] to run it on the infsup class
> from your Interval package.  Interval uses the standard Octave @result{}
> convention: in my patched version, I split on @result{} and some other
> heuristics.  It could be improved, see last bullet below.
>
> [1] https://github.com/catch22/doctest-for-matlab/pull/10
>
> I attach a log: most tests pass.  Oliver: I'm impressed!

Colin,

thanks for sharing the results. The interval package probably is an easy
target for your project. Most examples are syntactically very similar
and not very complicated. Any output from this package should be system
independent. Additionally the @example blocks in the package did not
have a lot of time to age and become wrong. ;-)

> I noticed:
>    * there are a few actual errors.

I found only one error with ldivide. The documentation string calls
mldivide by accident (bug 1) and your test happens to reveal a problem
in mldivide (bug 2). Lucky strike!

>    * there are some cases of @example used as a LaTeX alternative
>      (is there an @verbatim instead?)

Yes, the @example blocks have been used for ASCII art and do not contain
actual examples. The @verbatim should be a valid replacement (without
indentation). I am going to change the documentation.

>    * there a few minor (cosmetic?) errors: [-1, 5] to [-1, +5]

I would consider these actual errors and am going to fix the
documentation. A very early version of the package had a different
format for the output of signs.

>    * there are a couple cases were my current splitting
>      input/output based on @result{} fails.  (Personally I prefer
>      marking input with ">>" but the doctest code could instead be
>      refactored further.)

I found several problems with doctest:

intervaltotext: The @example block contains 3 consecutive inputs and
outputs. Without the missing “>>” for inputs there is a problem with
seperating them. Would it be sufficient to use three @group blocks in
the @example block?

eq, nextout: The output is boolean, but the documentation string shows
the console output as ans = 0 (or 1). I can change the documentation to
@result{} False (or True).

mulrev: The function returns two return values and the syntax used in
the @example is probably wrong for that purpose.

> Finally. I checked several functions in core: spdiags and svd are fairly
> close to testable.  qr, chol not really written with this sort of tool
> in mind.  IIRC, others warned me this was true of core Octave.
>
> Colin

I plan to improve the performance of console output for my package. I
can put your work into great use during regression testing for that change.

Following our discussion in February, I have implemented all @example
blocks in the package as %!test blocks. They check the return value
semantically and can be run by any user. However, doctest also checks
the @example blocks syntactically, which provides additional value. And
as the ldivide example tought us: The %!test blocks are not guaranteed
to be perfectly synchronized with their @example blocks!

Oliver


> On 02/02/15 18:23, Oliver Heimlich wrote:
>> Am 02.02.2015 um 18:42 schrieb Colin Macdonald:
>>> I've recently learned how to use `@result{}` 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
>>> `@result{}`...  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.
>>
>

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Jordi Gutiérrez Hermoso-2
In reply to this post by Colin Macdonald
On Fri, 2015-03-27 at 09:39 +0000, Colin Macdonald wrote:
> Finally. I checked several functions in core: spdiags and svd are fairly
> close to testable.  qr, chol not really written with this sort of tool
> in mind.  IIRC, others warned me this was true of core Octave.

I'd be quite happy to start rewriting examples so that they can be
parsed into doctests. I haven't been following your progress, so for
annoying lazy me, can you tell me what sort of things have to be done?

- Jordi G. H.



Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
In reply to this post by Oliver Heimlich
>> I noticed:
>>    * there are a few actual errors.
>
> I found only one error with ldivide. The documentation string calls
> mldivide by accident (bug 1) and your test happens to reveal a problem
> in mldivide (bug 2). Lucky strike!
>
>>    * there are some cases of @example used as a LaTeX alternative
>>      (is there an @verbatim instead?)
>
> Yes, the @example blocks have been used for ASCII art and do not contain
> actual examples. The @verbatim should be a valid replacement (without
> indentation). I am going to change the documentation.
>
>>    * there a few minor (cosmetic?) errors: [-1, 5] to [-1, +5]
>
> I would consider these actual errors and am going to fix the
> documentation. A very early version of the package had a different
> format for the output of signs.
>
>>    * there are a couple cases were my current splitting
>>      input/output based on @result{} fails.  (Personally I prefer
>>      marking input with ">>" but the doctest code could instead be
>>      refactored further.)
>
> I found several problems with doctest:
>
> intervaltotext: The @example block contains 3 consecutive inputs and
> outputs. Without the missing “>>” for inputs there is a problem with
> seperating them. Would it be sufficient to use three @group blocks in
> the @example block?
>
> eq, nextout: The output is boolean, but the documentation string shows
> the console output as ans = 0 (or 1). I can change the documentation to
> @result{} False (or True).
>
> mulrev: The function returns two return values and the syntax used in
> the @example is probably wrong for that purpose.

Colin,

I have added a doctest target into my maintainer Makefile [1], which
works out of the box together with you modifications for doctest-for-matlab.

I was able to make all doctests pass with a simple changeset [2]. There
is only one thing which I am not happy with: I could only make the
following example pass by splitting it into three separate @example
blocks. Three @example blocks produce very poor formatting in the HTML
documentation because of big margins between them. So, there should be a
different solution.

## x = infsup (1 + eps);
## intervaltotext (x)
##   @result{} [1.0000000000000002, 1.0000000000000003]
## y = nextout (x);
## intervaltotext (y)
##   @result{} [1, 1.0000000000000005]
## z = infsup (1);
## intervaltotext (z)
##   @result{} [1]

Oliver

[1] https://sourceforge.net/p/octave/interval/ci/default/tree/Makefile
[2]
https://sourceforge.net/p/octave/interval/ci/a1bf37f4dde28a03aa1a3cbdb50d42e476e3c75b/

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
On 28/03/15 12:09, Oliver Heimlich wrote:

> There
> is only one thing which I am not happy with: I could only make the
> following example pass by splitting it into three separate @example
> blocks. Three @example blocks produce very poor formatting in the HTML
> documentation because of big margins between them. So, there should be a
> different solution.
>
> ## x = infsup (1 + eps);
> ## intervaltotext (x)
> ##   @result{} [1.0000000000000002, 1.0000000000000003]
> ## y = nextout (x);
> ## intervaltotext (y)
> ##   @result{} [1, 1.0000000000000005]
> ## z = infsup (1);
> ## intervaltotext (z)
> ##   @result{} [1]

This should work:

## @example
## x = infsup (1 + eps);
## y = nextout (x);
## z = infsup (1);
## intervaltotext (x)
##   @result{} [1.0000000000000002, 1.0000000000000003]
## intervaltotext (y)
##   @result{} [1, 1.0000000000000005]
## intervaltotext (z)
##   @result{} [1]
## @end example

But I think I can easily change it to respect group so that the below
would work.  (And you also suggested this in your previous reply I
think).  Would that be fine from a formatting point-of-view?  IIRC, it
would only change pagination.

## @example
## @group
## x = infsup (1 + eps);
## intervaltotext (x)
##  @result{} [1.0000000000000002, 1.0000000000000003]
## @end group
## @group
## y = nextout (x);
## intervaltotext (y)
##   @result{} [1, 1.0000000000000005]
## @end group
## @group
## z = infsup (1);
## intervaltotext (z)
##   @result{} [1]
## @end group
## @end example


Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
Am 28.03.2015 um 13:19 schrieb Colin Macdonald:
> On 28/03/15 12:09, Oliver Heimlich wrote:
>> There
>> is only one thing which I am not happy with: I could only make the
>> following example pass by splitting it into three separate @example
>> blocks. Three @example blocks produce very poor formatting in the HTML
>> documentation because of big margins between them. So, there should be a
>> different solution.
>>

>
> This should work:
>
> ## @example
> ## x = infsup (1 + eps);
> ## y = nextout (x);
> ## z = infsup (1);
> ## intervaltotext (x)
> ##   @result{} [1.0000000000000002, 1.0000000000000003]
> ## intervaltotext (y)
> ##   @result{} [1, 1.0000000000000005]
> ## intervaltotext (z)
> ##   @result{} [1]
> ## @end example

Yes, this works. I would rather not be forced to change example because
of doctest.

> But I think I can easily change it to respect group so that the below
> would work.  (And you also suggested this in your previous reply I
> think).  Would that be fine from a formatting point-of-view?  IIRC, it
> would only change pagination.

I'd prefer this solution. However, the current generate-html adds
additional margins between @group blocks. They are smaller than the
margins between @example + @group blocks, but still very big. According
to texinfo the @group blocks should not add margins and only affect
pagination. Can we fix this in the generate-html package?

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

jbect
Le 28/03/2015 13:34, Oliver Heimlich a écrit :
> I'd prefer this solution. However, the current generate-html adds
> additional margins between @group blocks. They are smaller than the
> margins between @example + @group blocks, but still very big.
> According to texinfo the @group blocks should not add margins and only
> affect pagination. Can we fix this in the generate-html package?

Hello Oliver,

Is it a problem with the HTML generated by the generate_html package, or
simply a problem with the CSS ?

Can you provide a patch ? Otherwise, can you point me to a specific
example of this problem (in the interval package, for example) ?

@++
Julien


Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
In reply to this post by Jordi Gutiérrez Hermoso-2
On 27/03/15 21:08, Jordi Gutiérrez Hermoso wrote:
> I'd be quite happy to start rewriting examples so that they can be
> parsed into doctests. I haven't been following your progress, so for
> annoying lazy me, can you tell me what sort of things have to be done?

Maybe I should send a couple patches to give the idea?

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Søren Hauberg
In reply to this post by jbect


Den 28-03-2015 kl. 13:52 skrev Julien Bect:

> Le 28/03/2015 13:34, Oliver Heimlich a écrit :
>> I'd prefer this solution. However, the current generate-html adds
>> additional margins between @group blocks. They are smaller than the
>> margins between @example + @group blocks, but still very big.
>> According to texinfo the @group blocks should not add margins and
>> only affect pagination. Can we fix this in the generate-html package?
>
> Hello Oliver,
>
> Is it a problem with the HTML generated by the generate_html package,
> or simply a problem with the CSS ?
Have you looked at the HTML produced by 'generate_html'? One of the bugs
that haunted me was that 'makeinfo' does not close '<div>' tags, i.e. it
writes a '<div>' but does not add the matching '</div>' tag. Perhaps
this is at the root of your troubles?

Cheers
Søren

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
In reply to this post by jbect
Am 28.03.2015 um 13:52 schrieb Julien Bect:

> Le 28/03/2015 13:34, Oliver Heimlich a écrit :
>> I'd prefer this solution. However, the current generate-html adds
>> additional margins between @group blocks. They are smaller than the
>> margins between @example + @group blocks, but still very big.
>> According to texinfo the @group blocks should not add margins and only
>> affect pagination. Can we fix this in the generate-html package?
>
> Hello Oliver,
>
> Is it a problem with the HTML generated by the generate_html package, or
> simply a problem with the CSS ?
>
> Can you provide a patch ? Otherwise, can you point me to a specific
> example of this problem (in the interval package, for example) ?
>
> @++
> Julien

Julien,

each @group block within an @example block will be converted into a <pre
class="example"> block.

## @end group
## @group
Such a group change introduces an additional <pre> block between the
groups, which contains a single space.

However, when I omit the spaces, there is no additional <pre> block and
I am happy. ;-)
##@end group
##@group

I investigated this further and found more unintentional <pre> blocks.
Probably, the generate-html package should strip the spaces in front of
@ macros at the beginning of lines. What do you think?

Oliver

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

jbect
Le 28/03/2015 14:17, Oliver Heimlich a écrit :

> Am 28.03.2015 um 13:52 schrieb Julien Bect:
>> Le 28/03/2015 13:34, Oliver Heimlich a écrit :
>>> I'd prefer this solution. However, the current generate-html adds
>>> additional margins between @group blocks. They are smaller than the
>>> margins between @example + @group blocks, but still very big.
>>> According to texinfo the @group blocks should not add margins and only
>>> affect pagination. Can we fix this in the generate-html package?
>>
>> Hello Oliver,
>>
>> Is it a problem with the HTML generated by the generate_html package, or
>> simply a problem with the CSS ?
>>
>> Can you provide a patch ? Otherwise, can you point me to a specific
>> example of this problem (in the interval package, for example) ?
>>
>> @++
>> Julien
>
> Julien,
>
> each @group block within an @example block will be converted into a
> <pre class="example"> block.
>
> ## @end group
> ## @group
> Such a group change introduces an additional <pre> block between the
> groups, which contains a single space.
>
> However, when I omit the spaces, there is no additional <pre> block
> and I am happy. ;-)
> ##@end group
> ##@group
>
> I investigated this further and found more unintentional <pre> blocks.
> Probably, the generate-html package should strip the spaces in front
> of @ macros at the beginning of lines. What do you think?

I though I had solved this problem :

http://sourceforge.net/p/octave/generate_html/ci/c0ad0267e85bd1ec876469de30d7587c8aed8547/

Which generate_html are you using ? 0.1.6 or hg's tip ?

The patch deals with @group and @end keywords, are there other keywords
that should be handled similarly ?

I am preparing a release of generate_html these days, it should be ready
very very soon...

@++
Julien


Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Jordi Gutiérrez Hermoso-2
In reply to this post by Colin Macdonald
On Sat, 2015-03-28 at 13:08 +0000, Colin Macdonald wrote:
> On 27/03/15 21:08, Jordi Gutiérrez Hermoso wrote:
> > I'd be quite happy to start rewriting examples so that they can be
> > parsed into doctests. I haven't been following your progress, so for
> > annoying lazy me, can you tell me what sort of things have to be done?
>
> Maybe I should send a couple patches to give the idea?

How about we just give you push access and you start pushing them
yourself?

I mean, I still am willing to help you rewrite the docs, but I don't
see any reason why you shouldn't be allowed to modify our codebase
directly.

- Jordi G. H.






Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
In reply to this post by jbect
Am 28.03.2015 um 14:40 schrieb Julien Bect:
> Le 28/03/2015 14:17, Oliver Heimlich a écrit :
>> Am 28.03.2015 um 13:52 schrieb Julien Bect:
>>> Le 28/03/2015 13:34, Oliver Heimlich a écrit :
>>>> I'd prefer this solution. However, the current generate-html adds
>>>> additional margins between @group blocks. They are smaller than the
>>>> margins between @example + @group blocks, but still very big.
>>>> According to texinfo the @group blocks should not add margins and only
>>>> affect pagination. Can we fix this in the generate-html package?

>>> Is it a problem with the HTML generated by the generate_html package, or
>>> simply a problem with the CSS ?
>>>
>>> Can you provide a patch ? Otherwise, can you point me to a specific
>>> example of this problem (in the interval package, for example) ?

>> I investigated this further and found more unintentional <pre> blocks.
>> Probably, the generate-html package should strip the spaces in front
>> of @ macros at the beginning of lines. What do you think?

> I though I had solved this problem :
>
> http://sourceforge.net/p/octave/generate_html/ci/c0ad0267e85bd1ec876469de30d7587c8aed8547/

Julien,

I have not followed your submissions recently. The tip version solves
all problems. Well done!

Thus, only support for @group blocks in doctest is missing. doctest
could use @end group as a separator between expected output and the next
commands. However, this would be a little bit of a hack, because @group
could also be used within expected output if it is very long. Any better
ideas?

Oliver

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
On 28/03/15 16:07, Oliver Heimlich wrote:
> Thus, only support for @group blocks in doctest is missing. doctest
> could use @end group as a separator between expected output and the next
> commands. However, this would be a little bit of a hack, because @group
> could also be used within expected output if it is very long. Any better
> ideas?

I see, I had not thought of that.

Maybe need to implement stepping through the code, checking one command
at time.  This should be straightforward but will take me some time...
And I'm not hugely motivated as I personally prefer ">>" to mark each
command.

Alternatively (or perhaps additionally), any thoughts about adding a
@prompt{} command?

Colin

Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
In reply to this post by Jordi Gutiérrez Hermoso-2
On 28/03/15 14:14, Jordi Gutiérrez Hermoso wrote:
> How about we just give you push access and you start pushing them
> yourself?
>
> I mean, I still am willing to help you rewrite the docs, but I don't
> see any reason why you shouldn't be allowed to modify our codebase
> directly.

Maybe in principle, don't promise I'll do very much!

But to get started here's a patch for svd.  Some comments/questions:

1.  @example is not (semantically) a good alternative to tex.
     I used @verbatim as in this patch (and I think Oliver does
     the same in Interval).  But then how far to indent?


2.  This code (and others I've seen) split the command and
     the output across multiple @examples.  I propose changing
     this:
     @example
       some cmd
     @end example
     returns
     @example
     some output
     @end example

     into this:
     @example
       some cmd
       @result {} some output
     @end example

     Is that ok?


3.  "help strjoin" shows

     strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
           => 'Octave*Scilab*Lush*Yorick'

     Currently I would need to have "ans", like this

     strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
           => ans = 'Octave*Scilab*Lush*Yorick'

     But I think it might be nice to have doctest accept either,
     at least in the specific case of "ans".


svd_docs.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Colin Macdonald
On 28/03/15 17:39, Colin Macdonald wrote:

> 2.  This code (and others I've seen) split the command and
>      the output across multiple @examples.  I propose changing
>      this:
>      @example
>        some cmd
>      @end example
>      returns
>      @example
>      some output
>      @end example
>
>      into this:
>      @example
>        some cmd
>        @result {} some output
>      @end example
>
>      Is that ok?
I.e, the attached instead of the previous patch.

(Aside: can you tell from these patches if these are on the right branch
for submitting?  None of this should be for 4.0 I assume)

Colin

svd_docs2.diff (2K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: @example's as doctests

Oliver Heimlich
In reply to this post by Colin Macdonald
Am 28.03.2015 um 17:39 schrieb Colin Macdonald:

> On 28/03/15 16:07, Oliver Heimlich wrote:
>> Thus, only support for @group blocks in doctest is missing. doctest
>> could use @end group as a separator between expected output and the next
>> commands. However, this would be a little bit of a hack, because @group
>> could also be used within expected output if it is very long. Any better
>> ideas?
>
> I see, I had not thought of that.
>
> Maybe need to implement stepping through the code, checking one command
> at time.  This should be straightforward but will take me some time...
> And I'm not hugely motivated as I personally prefer ">>" to mark each
> command.
>
> Alternatively (or perhaps additionally), any thoughts about adding a
> @prompt{} command?
>
> Colin

I personally do not prefer the “>>” marker, because it makes copying the
code difficult.

The recent changes in generate_html make my first solution possible
again: The three blocks can be separated into three @example blocks,
which format well in console (help command) and in HTML now.

The doctest does not reset local variables between @example blocks, so
they can simply be used to group each pair of input and output.

## @example
## @group
## x = infsup (1 + eps);
## intervaltotext (x)
##   @result{} [1.0000000000000002, 1.0000000000000003]
## @end group
## @end example
## @example
## @group
## y = nextout (x);
## intervaltotext (y)
##   @result{} [1, 1.0000000000000005]
## @end group
## @end example
## @example
## @group
## z = infsup (1);
## intervaltotext (z)
##   @result{} [1]
## @end group
## @end example

Oliver

12