DOC: freeze old whatsnew notes?

[jorisvandenbossche]

A problem with using the ipython directory for the whatsnew/release parts of the docs (so that all code examples are run during the doc build), is that after a while when things change/get deprecated, these pages don't build correctly anymore, generating warnings/exceptions.

An example: http://pandas-docs.github.io/pandas-docs-travis/whatsnew.html#hdfstore, with the unique attribute that was removed recently in #6813

I don't think we should start updating the older whatsnew docs (they are a kind of historical overview), but we should do something as those doc build warnings are annoying. A proposal:

• after a release (or after some time), we run whatsnew/release once with the pandas version of that release, and replace all ipython directory blocks to literal code-blocks with output.
• we maybe add a warning at the top of each whatsnew that the code examples can be outdated

An alternative is to add :okexcept: to those ipython code-blocks; this would solve the warnings during the doc build, but not the 'faulty' output in the docs itself.

[jreback]

i think maybe easiest to simply comment out the code and say its been replaced in that version (and show the alternative). for most of these this should be easy just an argument name change. I'll put the example up for HDFStore.unique

replacing with code-blocks is ok too (though actually a nice comment IMHO is more informative)

[jorisvandenbossche]

That's also an option.
If we would choose to convert the code examples to code-blocks, this can easily be done by outputting rst instead of html (rst with processed extensions) with something like https://pythonhosted.org/sphinxcontrib-restbuilder/ I think.

But it's indeed maybe simpler and more informative to just adapt and comment that example.
An advantage of converting it to code-blocks would be that the doc builds would be slightly faster.

[jreback]

fixed HDFStore.unique issue in c1440e9

[jreback]

http://pandas-docs.github.io/pandas-docs-travis/whatsnew.html#v0-10-1-january-22-2013 (except for the typo of course!)

[jreback]

can you post what's still outstadning on this? (if you have handy)

[jorisvandenbossche]

Not that I know of. There are in any case no doc build warnings/errors at the moment. (but the problem is that you don't always notice it if something has changed in the output of the code so the explanation does not really make sense anymore).

[jreback]

ok...will leave open and i'll guess will just have to review all whats new for sensibility

[jorisvandenbossche]

I think we should just make a choice:

• just fix it when an issue comes up (at least those that we notice due to doc build errors, eg a removed keyword), and so close this issue now (no reason to keep it open I think. Errors will always be noticed in doc build).
• or convert older whatsnews to static code blocks (not too much work I think, should explore it)

The easiest solution is the first, although I have a slight preference for the second (I see it as an historical overview, and not as up to date docs. Downside is that if people are looking at older whatsnews they see possibly outdated code). But no strong opinion on this.