Re: Add doctest pkg to octave-forge

[Oliver Heimlich]

On 07.07.2015 23:47, Carnë Draug wrote:
> On 5 July 2015 at 10:49, Colin Macdonald <address@hidden> wrote:
> > On 03/07/15 17:33, Carnë Draug wrote:
> > > I actually think this would be useful in core.  Not as a separate function
> > > but as part of test().  If we start it as a package, then core can't use
> > > it
> > > itself.  What do you think?
> >
> > "then core can't use it": I assume you mean the core Octave build/test
> > process must not be made to depend on OF packages---which is certainly
> > reasonable.  Of course devs could nonetheless use it to test core functions,
> > just not as a part of the build process.
> >
> >
> > I don't think I have a strong opinion: does it have to be either or?
> >
> > Adding it to core means it will take some time until people (external to
> > Octave devs) can start to use it.  So we'd probably maintain it as a
> > separate package for at least a year or so anyway: perhaps it might as well
> > be an OF package during that time?
>
> Developing it as a separate package is more like to slow down incorporation
> into core.  It is not very common that code in a package gets moved into core.
> If that's the long plan, it's just easier to do it in core from the start.
>
> Also, it may look like it will slow down adoption, but I believe the opposite.
> If it gets incorporated into core as part of test(), everyone will
> automatically use it as soon as Octave 4.2 gets released (even if they don't
> know about it).  On my mind, being part of test() means that calling test on
> a function will automatically test the help text too.  There wouldn't be
> a doctest function as the namespace is polluted enough as it is. Others
> may have different opinions though.
>
> Of course, there may be more work to include it on core, so if you prefer a
> separate package, just say so, and I will create it on Octave Forge.
>
> Carnë

I like the idea of adding it to Core instead of Octave Forge, especially 
the part where doctesting will be done by the regular test function.

This has many advantages:
- No redundant code for finding files (recursion through dirs) etc.
- As Carnë mentioned, it will be automatically run together with the 
normal test, which is easier for the user and integrates well into any 
build processes
- Until 4.2 there will be much more feedback and we will see how well 
the functionality matches the common documentation / coding style
- After 4.2 the user reach will be much bigger
- There have been some improvements in the doctest function (compared to 
test). The regular test function would naturally benefit from these when 
they are carried over and integrated into Core.

However, there are also disadvantages: The current developers of doctest 
(Michael and Colin) do not have access to the Core repository. The patch 
tracker is a very slow mechanism for “outsiders”. Development would 
probably take place in a clone of the Octave repository. Better ideas? 
Commit access?

Also Octave Forge developers might not want to switch to the 4.2 branch 
yet. They could not use doctest until the release?!? No! The current 
doctest package from Github should already contain enough functionality 
for most—if not all—packages and could be used until then. At some point 
Forge developers will switch to 4.2 and the package is no longer needed. 
Am I missing something?

This step would tear the doctest package apart, which currently also 
supports matlab. However, I would not shed any tear over that (IMHO).

Oliver