Some changes can break the doc or the way it is built. Having Travis
build the doc could allow to detect these changes and to fix them before
merging them.
Travis CI relies on an old version of Ubuntu (12.04) that only provides
an old version of pandoc (1.9). This version of pandoc does not allow to
build the doc. Therefore, we must install a more recent version of
pandoc in Travis. As this install takes about 20 minutes, I set up a
cache. See Travis doc on cache:
http://docs.travis-ci.com/user/caching/#Arbitrary-directories
As a cache was set up, I extended it to pip. This is mostly useful for
the install of matplotlib that got speed up from several minutes to
about 4 seconds.
The first Travis run after this commit will be long (more than 20
minutes), but the subsequent run should be faster than what they were
previous to it. A python 3 test job is speed up from about 6 minutes to
about 4 minutes to to the faster install.
As for now, the doc is only built for python 2.7. Indeed, the doc
requires MDAnalysis that is not compatible with python 3. To avoid to
increase further the duration discrepancy between test runs for python 2
and python 3, the doc is built on a separate process. This is done using
build matrix with two different environment: test, and doc. See travis
doc for more details:
http://docs.travis-ci.com/user/customizing-the-build/.
Note that the version of pandoc we install in Travis is more recent than
the one used by Read the doc. This version discrepancy is to take into
account! If a change introduces the use of a feature not available in
the Read the docs version of pandoc, the Read the doc failure will not
be predicted by Travis.
Travis is planning a move to Ubuntu 14.04. This upgrade should allow us
to streamline the install of pandoc, as a recent enough version of
pandoc will be available through APT. It should also fix the version
discrepancy between Travis and Read the doc.
jbarnoud
commented
8 years ago
Some changes can break the doc or the way it is built. Having Travis build the doc could allow to detect these changes and to fix them before merging them.
Travis CI relies on an old version of Ubuntu (12.04) that only provides an old version of pandoc (1.9). This version of pandoc does not allow to build the doc. Therefore, we must install a more recent version of pandoc in Travis. As this install takes about 20 minutes, I set up a cache. See Travis doc on cache: http://docs.travis-ci.com/user/caching/#Arbitrary-directories
As a cache was set up, I extended it to pip. This is mostly useful for the install of matplotlib that got speed up from several minutes to about 4 seconds.
The first Travis run after this commit will be long (more than 20 minutes), but the subsequent run should be faster than what they were previous to it. A python 3 test job is speed up from about 6 minutes to about 4 minutes to to the faster install.
As for now, the doc is only built for python 2.7. Indeed, the doc requires MDAnalysis that is not compatible with python 3. To avoid to increase further the duration discrepancy between test runs for python 2 and python 3, the doc is built on a separate process. This is done using build matrix with two different environment: test, and doc. See travis doc for more details: http://docs.travis-ci.com/user/customizing-the-build/.
Note that the version of pandoc we install in Travis is more recent than the one used by Read the doc. This version discrepancy is to take into account! If a change introduces the use of a feature not available in the Read the docs version of pandoc, the Read the doc failure will not be predicted by Travis.
Travis is planning a move to Ubuntu 14.04. This upgrade should allow us to streamline the install of pandoc, as a recent enough version of pandoc will be available through APT. It should also fix the version discrepancy between Travis and Read the doc.