Tracking status of doctest passing on all Octave doc strings

gnu-octave / octave-doctest

Doctests for Octave/Matlab

https://gnu-octave.github.io/packages/doctest/

BSD 3-Clause "New" or "Revised" License

16 stars 4 forks source link

Tracking status of doctest passing on all Octave doc strings #188

Open mtmiller opened 5 years ago

mtmiller commented 5 years ago

It will be highly useful if all of Octave's core doc strings pass with doctest. Let's track the overall completion status of that goal here. That includes doctest issues that are blockers, Octave upstream issues preventing this, and lists of individual Octave doc strings that need to be worked on.

[x] handle doc example blocks that call format (#183)
[ ] document how to do this: is it just doctest . in hg checkout?
[x] do we need a release with the .oct file stuff?
[ ] start sending patches
- [x] https://hg.savannah.gnu.org/hgweb/octave/rev/f6730533820e
- [ ] https://savannah.gnu.org/patch/?8666

cbm755 commented 5 years ago

This issue seems as good as any, at least for high-level. I'll start editing a checklist into your first comment...

cbm755 commented 5 years ago

It might be good to try a release candidate for 0.7.0 on Octave just to make sure we haven't broken anything that would hinder this effort...

@mtmiller how do you actually do this? In the source tree after building?

make install
./run-octave
>> pkg install doctest-x.y.z+
>> doctest .

I get a lot of stuff like

/tmp/octave-help-OOYWOO:702: unknown command `DOCSTRING'
/tmp/octave-help-OOYWOO:704: unknown command `DOCSTRING'
/tmp/octave-help-OOYWOO:706: unknown command `DOCSTRING'
/tmp/octave-help-OOYWOO:708: unknown command `DOCSTRING'
/tmp/octave-help-OOYWOO:710: unknown command `DOCSTRING'

And maybe we shouldn't be testing both .txi and .texi? Just the .texi files which are autogenerated from .txi?

mtmiller commented 5 years ago

Yeah, I don't really remember how I did it before, but here's a way that works whether or not Octave is already installed, I think this gets pretty close to all documented functions. In the build tree

doctest ([__builtins__; 'libinterp/dldfcn'; '../scripts'])

or in a running installed Octave

doctest ([__builtins__; __octave_config_info__('octfiledir'); __octave_config_info__('fcnfiledir')])

cbm755 commented 5 years ago

Thanks! I tried the 0.7.0 RC with Octave 6.0.0 install,, checked out today:

__builtins__: hangs on popen2
__octave_config_info__('octfiledir'): FAIL 1/1
__octave_config_info__('fcnfiledir'): FAIL 74/214

With doctest-0.6.1:

__builtins__: hangs on popen2
__octave_config_info__('octfiledir'): N/A (not supported)
__octave_config_info__('fcnfiledir'): FAIL 73/214

So no significant differences between 0.6.1 and 0.7.0, which is good.