add travis doc build

[cpcloud]

not sure if this is worth the trouble but it may catch version incompatibility issues and other bugs not caught by the test suite.

[jtratner]

Check out jtratner/pandas@2c285ea . I think that covers what you're looking for. It really depends how long the job takes - https://travis-ci.org/jtratner/pandas/jobs/7895295

[cpcloud]

looks ok, but i'm thinking about the possible numpy dependency issue here. there's a few examples in the docs that throw an error for slightly older versions of numpy...i wouldn't want this to always fail because of that. i was actually thinking only a doc build and no other tests so another row in the build matrix...

[jtratner]

@cpcloud I updated it a bit - jtratner/pandas@bcae377 . It does mean that the test now has to wait for one of the other tests to finish (since it looks like Travis will only run 5 tests concurrently), which means it adds about 20 minutes to testing time. Would it make more sense to incorporate with one of the other version tests?

[cpcloud]

An extra 20 minutes is unacceptable IMHO. Travis is already slow enough. Probably better to put it in one of the 2.7 like u had. Just need to make sure that no exceptions are generated (which is the point really...) but need to see if there are any benign exceptions generated by numpy... I get these when I run the doc build and I believe it's because I use dev numpy.

[cpcloud]

i'm going to test a doc build on pip install <dependency>-backed pandas to see if any warnings are generated...if not this might be a go pending someone else's review...

[jreback]

can we shove this in the 2.7 non-us build?

[cpcloud]

probably would be ok, i just want to check those deps first...

[jtratner]

So, my branch wasn't actually testing doc building, because it didn't have make doc in the Makefile, but this wasn't causing an error. This is fixed now, but it required pulling in the Makefile commit too... (jtratner/pandas@8994c26)

[cpcloud]

@jreback can assume that the doc-building machine has scikits.timeseries installed so that it won't raise?

[jreback]

yep has all deps AFAIN

[jtratner]

Okay, this doesn't work right now, because make docs is set to be silent. Also, it looks like sphinx doesn't get installed, so I'll have to fix again.

[cpcloud]

also there are some doc build issues that i'm fixing right now...for some reason when branch depending on numpy versions in timeseries.rst i get a few errors in visualisation.rst. probably some variable aliasing somewhere...

[jtratner]

Looks like it needs IPython too ... check out the failing build: https://travis-ci.org/jtratner/pandas/jobs/7913726

(at least we now know that it errors out here)

[cpcloud]

yep just add a pip install ipython

[cpcloud]

if u do that you might want to add ipython to ci/print_versions.py

[jtratner]

@cpcloud yeah, added that and also added sphinx to versions too

[jtratner]

@cpcloud now it finds a weird unicode issue - do you get this too? https://travis-ci.org/jtratner/pandas/jobs/7915482

[cpcloud]

might be because of the locale...see if u can repro it on ur machine...i'll try in a vagrant box

[cpcloud]

actually before we do that can u try running it in the non zh_CN locale version

[jtratner]

yeah, though I have 2 builds pending so it might take a while.

On Sat, Jun 8, 2013 at 10:12 PM, Phillip Cloud [email protected]:

actually before we do that can u try running it in the non zh_CN locale
version

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3800#issuecomment-19159467
.

[cpcloud]

@jtratner any luck/progress/decisions to abandon this? i would happily close if this is going to waste time

[jtratner]

@cpcloud I have to look back, but I think it was just fixing the Makefile to not squelch errors. Ultimately depends on whether you want to accept #3803 , because it can then just run make doc. It doesn't add that much time to the build (I don't think) - greatest amount of time is compiling and installing the build itself.

[cpcloud]

yes everything on travis is completely dwarfed by build time although u can put PTF in ur commit message and it will try to use a cached build. i haven't used it a lot but maybe i should start

[jtratner]

That's interesting.... Does it try to cache between commits?
On Jun 13, 2013 5:16 PM, "Phillip Cloud" [email protected] wrote:

yes everything on travis is completely dwarfed by build time although u
can put PTF in ur commit message and it will try to use a cached build. i
haven't used it a lot but maybe i should start

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3800#issuecomment-19425599
.

[jtratner]

@cpcloud building docs works now, it adds very little time to the overall build time, plus this build shows that it actually fails on errors :P https://travis-ci.org/jtratner/pandas/builds/8261960 [turns out there was a print cmd instead of print(cmd) in make.py]

[cpcloud]

probably not necessary to build on python 3 and python 2 unless the docs are built on that. @changhiskhan what python version are you running on the doc-building box?

[jtratner]

@cpcloud yeah, that's not what I'd put in the merge to pandas if we included at all...I mostly wanted to see if it would fail (which, of course, it did :P)

[cpcloud]

btw makefile stuff is nice 👍

[cpcloud]

@jreback @y-p any opinions here? this could save some minor headaches but also cause a few since another thing is added to travis...

[jtratner]

It probably should be added to a full build, else it will skip things that
can't import.
On Jun 21, 2013 9:19 PM, "Phillip Cloud" [email protected] wrote:

@jreback https://github.com/jreback @y-p https://github.com/y-p any
opinions here. this could save some minor headaches but also cause a few
since another thing is added to travis...

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3800#issuecomment-19848378
.

[cpcloud]

@jtratner @jreback I didn't realize they were being built by travis, my mistake. Should I reopen?

[jorisvandenbossche]

It is actually not fully clear to me what docs are exactly built:

• the docs are built for every PR (for every travis build) on build 3, where you can see the log output, but not the docs itself. Would that also be possible?
• the docs are also uploaded to http://pandas-docs.github.io/pandas-docs-travis, but which exactly? Not every build on travis is uploaded? How is this scheduled?
• I think ideally we would also have a dev doc build including the api docs, but I assume this was left out as this takes to much time on travis?

[jreback]

Docs are built only on the 2.7 build for all travis runs, but the upload ONLY happens on master (which makes sense), otherwise it fails (but the doc log is always their).

The api docs are NOT built as they take a lot of time. The build is actually in the background while network tests are running. @y-p did a nice job on this!

A py3 doc build could be done (just add it in travis).

You could modify build_docs.sh to do just about anything, but the problem is where would they go?
in theory you could have a site somewhere where they are put referenced by travis build number. Anyone want to do this? (it could actually be on the users github site which allows hosting!)

[jorisvandenbossche]

Thanks for the clarification!

[jorisvandenbossche]

I was thinking, would it be an option to have a seperate travis build for only the docs (and then maybe the api can be included), as a build that is not included in the fast-finish matrix so it is not delaying the tests?
(but not that I have much knowledge about this)

[jreback]

its not that hard to add another build (as we have an optional part of the matrix, e.g. the numpy 1.9 build is their).

you could certainly build the docs, then write the log file, then parse the log file and fail it appropriately, e.g. say you fail on certain types of warnings.

ok..let's reopen if you want me to add a build I can easily, then you could tweak the build script and test for it.

[jorisvandenbossche]

Hmm, in principle we could search for something like

>>>-------------------------------------------------------------------------
Exception in

in the doc logs and let travis fail.

Something else, Read The Docs also provides automatic updating of your docs for every commit to master (and also some other maybe interesting features: http://read-the-docs.readthedocs.org/en/latest/features.html).

[jreback]

read the docs doesn't build extensions - so won't work for us iirc

[jorisvandenbossche]

@jreback ah yes, indeed, that is the case

Something like this jorisvandenbossche@b086afd would let travis fail if there is an exception in the code examples of the doc build (with the doc build in travis build 3 as is the case now, so without adding an extra build. That could be a start). Result of travis you can see here: https://travis-ci.org/jorisvandenbossche/pandas/jobs/22765601 (the third failed because of the docs).

[jorisvandenbossche]

Something else, the scipy version in the 2.7 build (where the docs are built) is too old (scipy 0.10) for the docs (you get an exception in the interpolation section, ImportError: Your version of scipy does not support PCHIP interpolation.). Is this a problem to use a more recent scipy? Or is it because we want to test against the oldest supported scipy version?

[jreback]

building a wheel for scipy 0.13.3 now for the 2.7 build. this is all done in the pandas/ci/speedback/build.sh script. then upload to the pandas.pydata.org site.

i'll post when its done.

[jreback]

how much extra time do you figure build the full docs is to versus the with --no-api

[jorisvandenbossche]

Well, I think a full doc build is about 10 mins, while --no-api is something like 2-3 minutes (rough estimates). So a lot longer as the test suite I think? (as most time on travis is spent installing all packages?)

But maybe this are two not necessarily intertwined issues:

• checking the doc builds for exceptions (jorisvandenbossche@b086afd) and letting travis fail. For this, it is not necessary that the api docs are included, as only exceptions occur in the written docs (with ipython directives). At least, in the commit, I am only checking for that. I think that is the most important to check (we could also check for sphinx warnings, but then we should first have it completely warning free, which is not the case)
• It would be nice to also have the dev version of the api docs on the online dev docs, but this does not need to happen for every PR, so it shouldn't be necessarily included in the travis build (although this would be a handy way to have it)

[jreback]

Ok, maybe easiest way to proceed is to add a validation step in build_docs.sh. It can be a python script! that you can print to stdout for whatever; if you have an error, then just return a non-zero exit code and the build will fail (otherwise return 0). You can download the /tmp/doc.log to test from a build. Then the 2.7 build will fail if their is an exception (or whatever in the doc script).

just put it at the end of the build_docs.sh, scan the /tmp/doc.log and exit -1 if you want

fyi....scipy is now updated and docs building correctly http://pandas-docs.github.io/pandas-docs-travis/missing_data.html#interpolation

[jorisvandenbossche]

@jreback Thanks!

Well, I first put it in build_docs.sh, but then it complained because the /tmp/doc.log is actually the log of build_docs.sh, so I copied it to script.sh (jorisvandenbossche@b086afd).
It worked, but it complained (but maybe I can silence that)

[jreback]

you may have to wrap that in something like

if [x"$DOC_BUILD" != "x"]; then

to only do this on the doc builds.....

[cpcloud]

you can test for a nonempty string with

[ -n "$DOC_BUILD" ]

[jtratner]

@jorisvandenbossche - that looks like a nice and simple way to check
whether the docs failed. Does that get tripped up by expected Exceptions?