Build GMT docs #175

seisman · 2018-11-09T14:42:05Z

This PR adds GMT documentations builds. Since the sphinx of travis's OS (Ubuntu 14.04) is too old, I install python and sphinx via miniconda.

joa-quim · 2018-11-09T18:02:41Z

Does this mean that the docs are going to be (re)build for every commit?

seisman · 2018-11-09T18:14:07Z

@joa-quim Yes.

joa-quim · 2018-11-09T18:17:48Z

So, I'm afraid this is not such a good idea. Building the docs is a quite lengthy process and I do not see why a commit in the code would trigger it when the the two are not related.

seisman · 2018-11-09T18:18:46Z

As mentioned in #53, it's possible to use some magic strings like +DOCS to dynamically trigger the documentations build.

PaulWessel · 2018-11-09T18:18:52Z

@leouieda and I have discussed this. Using this feature depends on how quick it will be to build. As it is now, all illustrations as stored as PS files and there is a conversion to PNG (and maybe PDF) taking place during the docs build. We may find that we should also store the PNGs to avoid this step except when the PS has changed. If it takes too long to build then we may wish to make such changes.

PaulWessel · 2018-11-09T18:20:42Z

It is not possible to know for sure that a code change does not have an effect on the docs. if we fit a bug in surface or a plot tool it may cause small changes in the plots.

joa-quim · 2018-11-09T18:24:26Z

Yes, clean builds also build the PDF and, at least on Win, I think is ex19 alone takes minutes to create.
I really think we should not build the docs when there were no changes whatsoever on them.

joa-quim · 2018-11-09T18:26:23Z

It is not possible to know for sure that a code change does not have an effect on the docs. if we fit a bug in surface or a plot tool it may cause small changes in the plots.

Bur aren't the tests exactly for that? And that small change wouldn't go unnoticed?

seisman · 2018-11-09T18:30:51Z

@PaulWessel @joa-quim Travis supports cron jobs. Currently, the master branch will be built every month. Maybe we can change the cron job settings and build the master branch everyday.

If a build is triggered by a cron job, then we build the docs and also tests. Otherwise, we only build the sources, which is much faster.

seisman · 2018-11-09T18:32:21Z

The travis docs say that:

To check whether a build was triggered by cron, 
examine the TRAVIS_EVENT_TYPE environment variable to see if it has the value cron.

PaulWessel · 2018-11-09T18:53:18Z

Perhaps a cron job is an acceptable solution. I have gotten used to running the full tests before I submit a pull requests. On my 24-core Mac the tests take ~3 minutes. Building the entire docs from scratch is a bit faster since there are fewer PS to PNG processes; it takes 2.5 minutes. If my patch breaks something in the tests I can then fix before finalizing the PR. The cron job would instead be helpful to make sure we have a pretty recent version of the full docs available for users to browse. Maybe weekly cron?

leouieda · 2018-11-10T00:02:10Z

Bur aren't the tests exactly for that?

You're right. Building the docs always is probably not a great solution.

@seisman adding an if that checks for TRAVIS_EVENT_TYPE would be enough to make it trigger only in cron jobs. I think Travis can probably handle a nightly build.

leouieda

@seisman thanks for setting this up!

leouieda · 2018-11-10T00:04:42Z

.travis.yml

+ - TRAVIS_EVENT_TYPE=cron
+ - if [ "$TRAVIS_EVENT_TYPE" == "cron" ]; then
+ export PYTHON=3.6
+ export CONDA_REQUIREMENTS="ci/requirements.txt"


No need for a requirements file. You can set CONDA_INSTALL_EXTRA="sphinx" (see here).

leouieda · 2018-11-10T00:09:11Z

.travis.yml


 before_install:
 # Install GMT dependencies
 - bash ci/travis-setup.sh
+ - if [ "$BUILD_DOCS" == "true" ]; then
+ # Install GMT documentation dependencies
+ # Get the Fatiando CI scripts


Travis doesn't like these comments inside blocks. You have to put them out of the if or they can't parse the yml file.

leouieda · 2018-11-10T00:09:43Z

.travis.yml


 install:
 # Build and install GMT
 - bash ci/travis-build.sh;
+ - if [ "$BUILD_DOCS" == "true" ]; then
+ # Build GMT documentations
+ bash ci/travis-build-docs.sh;


Do we need a script for this?

The build should probably be part of the script block as well since this is pretty much part of the tests.

leouieda · 2018-11-10T00:13:08Z

.travis.yml

+ - if [ "$TRAVIS_EVENT_TYPE" == "cron" ]; then
+ export PYTHON=3.6
+ export CONDA_REQUIREMENTS="ci/requirements.txt"
+ export BUILD_DOCS=true


Suggested change

export BUILD_DOCS=true

Probably no need for this variable as well since we're only building on cron jobs.

leouieda · 2018-11-10T00:14:40Z

.travis.yml


 before_install:
 # Install GMT dependencies
 - bash ci/travis-setup.sh
+ - if [ "$BUILD_DOCS" == "true" ]; then


Suggested change

- if [ "$BUILD_DOCS" == "true" ]; then

- if [ "$TRAVIS_EVENT_TYPE" == "cron" ]; then

Could probably merge this block with the one further up. The env block is for setting the build matrix.

leouieda · 2018-11-10T00:15:32Z

.travis.yml


 install:
 # Build and install GMT
 - bash ci/travis-build.sh;
+ - if [ "$BUILD_DOCS" == "true" ]; then


Suggested change

- if [ "$BUILD_DOCS" == "true" ]; then

- if [ "$TRAVIS_EVENT_TYPE" == "cron" ]; then

seisman · 2018-11-10T02:32:18Z

@leouieda I've made changes as requested. Please review it again.

leouieda · 2018-11-10T03:07:18Z

@seisman looks good to me. The docs seem to build without error and it takes 223s so not too bad. Should we set this to run nightly?

leouieda · 2018-11-10T03:07:41Z

This is good to merge if @seisman has nothing more to add.

seisman · 2018-11-10T03:14:16Z

Should we set this to run nightly?

@leouieda I've set a nightly build. Feel free to set it weekly or monthly.

leouieda · 2018-11-10T03:17:15Z

Perfect!

Uses the new LibGMT.info to check if GMT is at least 6.0.0. Raises a GMTVersionError exception if it's not. It would be great if we could check this upon instantiation but that wouldn't work because `LibGMT.get_default` requires an active session. So the only logical place to put this is in `LibGMT.__enter__` after the session is created. The session is closed before the exception is raised. Fixes GenericMappingTools#171

seisman force-pushed the build-docs branch from 4597b17 to f903e85 Compare November 9, 2018 15:44

Build GMT docs

1704f09

seisman force-pushed the build-docs branch from f903e85 to 1704f09 Compare November 9, 2018 15:47

seisman changed the title ~~WIP: Build GMT docs~~ Build GMT docs Nov 9, 2018

seisman requested a review from leouieda November 9, 2018 16:02

seisman added 2 commits November 9, 2018 14:03

Build docs in cron builds only

191e3fd

Manually trigger docs build

ebf40fd

leouieda requested changes Nov 10, 2018

View reviewed changes

seisman added 4 commits November 9, 2018 20:49

fixes

e9625a9

fix

8abeace

fix2

a0e9539

Remove TRAVIS_EVENT_TYPE

e4609bf

leouieda approved these changes Nov 10, 2018

View reviewed changes

seisman merged commit 75d6b57 into master Nov 10, 2018

seisman deleted the build-docs branch November 10, 2018 03:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Build GMT docs #175

Build GMT docs #175

seisman commented Nov 9, 2018 •

edited

Loading

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

joa-quim commented Nov 9, 2018

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

seisman commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

leouieda commented Nov 10, 2018

leouieda left a comment

leouieda Nov 10, 2018

leouieda Nov 10, 2018

leouieda Nov 10, 2018

leouieda Nov 10, 2018

leouieda Nov 10, 2018

leouieda Nov 10, 2018

leouieda Nov 10, 2018

seisman commented Nov 10, 2018

leouieda commented Nov 10, 2018

leouieda commented Nov 10, 2018

seisman commented Nov 10, 2018

leouieda commented Nov 10, 2018

	- if [ "$BUILD_DOCS" == "true" ]; then
	- if [ "$TRAVIS_EVENT_TYPE" == "cron" ]; then

Build GMT docs #175

Build GMT docs #175

Conversation

seisman commented Nov 9, 2018 • edited Loading

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

joa-quim commented Nov 9, 2018

joa-quim commented Nov 9, 2018

seisman commented Nov 9, 2018

seisman commented Nov 9, 2018

PaulWessel commented Nov 9, 2018

leouieda commented Nov 10, 2018

leouieda left a comment

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

leouieda Nov 10, 2018

Choose a reason for hiding this comment

seisman commented Nov 10, 2018

leouieda commented Nov 10, 2018

leouieda commented Nov 10, 2018

seisman commented Nov 10, 2018

leouieda commented Nov 10, 2018

seisman commented Nov 9, 2018 •

edited

Loading