Repository navigation
Enable doctest for io.fits narrative docs #6010
Description
doctest-skip is used quite widely in the io.fits docs (e.g. in docs/io/fits/usage/table.rst). We need to aim to make most of the snippets tested, ideally it would be done easily with the addition of a few small fits files, either to this repo or to data.astropy.org
Reacted by P. L. Lim, Marten van Kerkwijk, Simon Conseil and Michael Seifert
Activity
pllim commentedon May 5, 2017
That is a good idea. We have had reports before that the examples don't actually work when someone runs them (I think those were fixed though).
bsipocz commentedon May 5, 2017
@pllim - Yes, #6009 urged me to open this issue, as that PR is not a real solution for the problem. Let alone most of the PRs opened through the docs GH integration are generating more work than they solve when opened to the wrong branch.
pllim commentedon May 8, 2017
Update: I spoke to @jhunkeler and he might take this on when his other projects calm down a little in a few weeks. Of course, this does not prevent anyone from contributing. First come, first serve.
bsipocz commentedon May 8, 2017
@pllim - Excellent!
saimn commentedon May 9, 2017
Good idea, but the issue is that for many examples the FITS files are not available. So one need to change the examples to use other FITS files, possibly from
astropy/io/fits/tests/data. (Fordocs/io/fits/usage/table.rstit was even worse before ddd3a4f ;), the remaining examples could be easily adapted).pllim commentedon May 9, 2017
Yes, either use existing local data or host the new data at the remote data server and mark it as remote doctest.
bsipocz commentedon May 9, 2017
@saimn - Yes, exactly that's the plan. Most of those examples are using dummy small fits files, so they could live in this repo, while others could live at data.astropy.org with the rest of the files.
saimn commentedon Oct 7, 2017
Fixed by #6664 , thanks @MSeifert04 🎉
MSeifert04 commentedon Oct 7, 2017
The
verifydocumentation is still "doctest-skip" because I didn't understand some of it (and several parts didn't work the way the documentation stated) and Warnings aren't checked by the doctests.So I'm not sure if this issue is fully adressed.
saimn commentedon Oct 7, 2017
Ok, I thought you skipped some examples because testing warnings does not work (?). Not sure if it's realistic to have all examples tested, that's why I closed the issue, but having examples that does not work as documented is more problematic. Maybe it deserves a specific issue ?
MSeifert04 commentedon Oct 7, 2017
@saimn Yes, a new issue would be fine. I planned to work some more on that this weekend but it shouldn't be forgotten if I don't have time to finish it.