This pull request is being automatically deployed with ZEIT Now (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://zeit.co/gmt/pygmt/119cxm068
🌍 Preview: https://pygmt-git-fork-weiji14-continuous-docs.gmt.now.sh

Ok, this is almost ready! Previews of the website can be viewed by clicking on the 'View deployment' button:

The bot is a lot noisier than I expected, but I've toggled on a silent flag that should 🤞 stop it from commenting on Pull Requests and commits once this PR is merged in.

Another thing worth considering is the related Deploy Summary Integration app (see review) that would detect changes to the pages and post a screenshot and direct link to the said changes. This will need to be installed (and might add more noise to our PRs) so looking to see what everyone thinks.

@weiji14 thanks for taking the time! This looks really cool. Is the now service building the docs or are they being deployed from the CI? Since all our CIs build the docs anyway, would it be easier to deploy from there? The problem is that keep these build systems alive takes quite a bit of time and effort, so it would be good to explore all options before adding a new one.

@weiji14 thanks for taking the time! This looks really cool. Is the now service building the docs or are they being deployed from the CI?

Yes, the now service is building them using npm.

Since all our CIs build the docs anyway, would it be easier to deploy from there? The problem is that keep these build systems alive takes quite a bit of time and effort, so it would be good to explore all options before adding a new one.

I hinted at #342 (comment) that this is indeed possible, but would require setting a token/secret variable. We could probably disable those documentation builds in a separate PR to speed them up?

The thing is, each of the built documentation sites have to be hosted online somewhere and given a unique url, which none of our current CIs are able to provide. Github Pages does do a build but is limited to one url. Another option I've looked at is netlify that does CD as well, but their pricing structure isn't as good as Now's.

Slightly off-topic but have you guys ever thought of migrating to gitlab? They have the possibility of ci/cd stuff directly built in so that you don't have to use different external apps that one has to somehow connect to... And the most important part: a single point of maintenance! Have a look here: https://docs.gitlab.com/ee/ci/introduction/index.html

We could probably disable those documentation builds in a separate PR to speed them up?

I’m not too keen on that since he docs builds are a sort of test. But to all builds need to do this (probably only one per OS would be good).

The thing is, each of the built documentation sites have to be hosted online somewhere and given a unique url, which none of our current CIs are able to provide. Github Pages does do a build but is limited to one url. Another option I've looked at is netlify that does CD as well, but their pricing structure isn't as good as Now's.

And using a key won’t work for forks because they aren’t decrypted for these builds (rightly so). But there are ways of storing build artefacts in Azure and Travis (which could be the html).

have you guys ever thought of migrating to gitlab

Yes but the problem is that everyone is here on GitHub, which makes it much easier to recruit contributors. But it is tempting.

Agreed that the documentation builds (which creates figures) does provide provide some 'integration' testing. Also with the Gitlab argument, Github does have Github Actions now which can be used to do CI/CD, but again, this topic is getting sidetracked too much...

Are there any outstanding issues with this PR @leouieda, or is it ready for approval/merge? I'm actually waiting to get this merged in to start working on some gallery examples. The workshop is coming up soon...

@weiji14 would you mind inserting some comments in the two files included here about what they are? Also, did this setup require signing up for these services? If so, were they done with your personal account? Would you mind posting some more information about this here so we can I have a record in case someone else need to manage this in the future? One thing we want to avoid is having a single person be able to access/manage things (which reminds me, we need to add you to Azure and PyPI).

Sorry for holding this up but PRs are meant for discussion before we commit to a given feature. It’s much easier to add things than it is to remove them later (granted, not in the case of this PR). I want to encourage a culture of deeper discussion of things before giving the 👍 and merging, even if that means going a bit slower in PyGMT than GMT core.

No don't apologize! I totally understand from a maintenance point of view (having worked on >10 year old legacy code before). A quick search shows that it isn't easy to add comments json files (see https://stackoverflow.com/questions/244777/can-comments-be-used-in-json) but I'll look around a bit more.

In terms of the Now account setup, I've set up a 'gmt' organization and I'm currently the 'owner', with @seisman being an user. I'll send an invite to your email too actually. Edit: I've set you two up with 'owner' permissions.

@weiji14 i thought that might be the case. Don’t worry too much about it. What you can do is include a section in MAINTENANCE.md which briefly explains the setup, files involved, and links to services so we can easily find them.