Add documentation to Travis builds. - #3240

I don't understand anything about Travis configuration. Does it only build the documentation only on master right now?

This will (eventually, once it works), build it on every PR. The next step (not here) will be to upload it somewhere, but that will only be on master, given Travis-CI's security constraints.

I think this is ready for final review (and sorry, needs a cherry-pick).

This builds the docs on Travis -- with gazillions of warnings and imperfectly -- and then runs linkchecker on it. This should prevent things like #3253 and #3246 from reappearing.

There are a couple of follow-ons that I think should be done as subsequent PRs:

• Clean up all documentation formatting warnings so that we can "error on warning" and catch formatting errors earlier on Travis.
• Clean up all warnings from rendering the examples (I know @jenshneilsen has been working on those lately), so that we can use this as a smoketest for all of the examples.
• Post the docs somewhere, but that will require latex and graphviz (at least).

DOWNSIDE WARNING: It takes over 30 minutes to build the docs on Travis, so given the parallelism, and the next longest configuration is only 10 minutes, this does add significant time to how long it takes to run the tests.

@mdboom Thanks! This looks great. Shame about the build time, though. Perhaps I can look at profiling/optimising the doc build (this I can do independently and should not hold up this PR). Also, I'm not sure the cherry-pick is essential for this PR.

On the other hand, we are clever enough to look at the build and see that just the doc test is still running.

Is it fair to keep piling heavier computational burdens on Travis? Is there any mechanism for triggering doc builds only occasionally, as an alternative? Rather than automatically with every PR modification?

@mdboom, can we speed up Travis by using apt-get to install more of the dependencies, such as numpy?

@mdboom, OK, I see the answer to my question is no; we're stuck with pip. This is incredibly inefficient, computationally, but it seems to be inherent in the way Travis works; it allows them to minimize the number of VMs they start with.

An alternative is to install miniconda and install other packages from there...

One possible significant portion of the test runtime might be the fontcache
build. Maybe that could be addressed, somehow?

On Thu, Jul 17, 2014 at 4:07 PM, Eric Firing notifications@github.com
wrote:

@mdboom https://github.com/mdboom, OK, I see the answer to my question
is no; we're stuck with pip. This is incredibly inefficient,
computationally, but it seems to be inherent in the way Travis works; it
allows them to minimize the number of VMs they start with.

—
Reply to this email directly or view it on GitHub
#3240 (comment)
.

I have had good experience with miniconda +1 on that. It also serves as a good install guide

We do have the "--small" doc build option, which I had forgotten about, which skips the PDF and hi-res PNG examples. That might build a little faster and still gets us most of what we want out of testing it.

I'm 👍 on moving to miniconda. I've created #3273 for that. Don't know if I'll have time soon -- anyone who wants to take it on can self-assign.

@WeatherGod: I think the fontcache generation is on the order of single-digit seconds at worst. It matters for starting up scripts, but as part of a 10-30minute testing time I doubt it's worth the trouble of speeding up.

I hope to get the last test warnings fixed next week.

I think it is worth cherry picking this (but maybe hold off until after we have 1.4.0 released, it it be good to have these builds running for the maintenance branch .

Re-tagging to 1.4.x

I cherrypicked this into v1.4.x at 67d141e.