add (automatic) pkgdown pages

[goldingn]

For some reason, I only just spotted pkgdown which automatically produces pretty web pages for R package docs, using github pages. It would be great to implement this for both the zoon package and the modules repo, so we have nice pages to send people to.

Generating the pages is fairly easy, so long as we remember to run pkgdown::build_site() on each commit. However we're liable to forget, and it would be awesome if the docs could be updated automatically on each successful master Travis build. That should be doable, via this method.

Given Travis will be pushing, we should probably stick to using the gh-pages branch for github pages, rather than the docs directory on master (as suggested in pkgdown).

I'll have a punt at this now (on a new branch) so this is just to document what I'm up to and track progress. There will probably be some tidying needed before the pages are pretty-looking.

[goldingn]

example zoon site now up at: http://goldingn.github.io/zoon

[goldingn]

The automated build setup looks like it should work, but my travis builds keep failing due to issues in occurrence modules; presumably the GBIF API being flaky as usual.

Will test it some more when they start passing.

[goldingn]

and here's the modules page: http://goldingn.github.io/modules/ No automation set up on that one, I'll put that in when I get the other one working.

[AugustT]

This all looks great!

[AugustT]

So this works because GitHub knows that a branch called gh-pages is a website? This is all very clever!

[AugustT]

I'm removing SpOcc from tests in the future

[goldingn]

Yup, you can point pages either to the gh-pages branch, to a folder 'docs' on master, or to master itself. The auto-building is the tricky bit.

[AugustT]

yeah... I saw the the .sh script.... looks taxing!

[goldingn]

note to future self: make sure the ssh keypair doesn't have a passphrase :/ getting there ...

[goldingn]

More notes for future me:

1. create a gh-pages branch
2. locally create an ssh keypair named deploy_key (private: deploy_key, public: deploy_key.pub) with no passphrase (follow these instructions, but just hit return for the passphrase)
3. from the repo's github page, navigate to settings/deploy keys and paste the contents of deploy_key.pub into a new deploy key, wand check the read/write access box
4. encrypt the private key with the travis CLI (deploy_key -> deploy.enc) as described here and copy the encryption label as described in the link
5. commit the Travis-encrypted private key (deploy_key.enc) to master
6. copy the .deploy_pkgdown.sh script as-is to master.
7. modify .travis.yml's env: on master to add - ENCRYPTION_LABEL: "<encryption label>" and - COMMIT_AUTHOR_EMAIL: "<email>" (filling in the encryption label and your email address for auto-commits)
8. modify .travis.yml's after_success: on master to add - bash .deploy_pkgdown.sh
9. modify .travis.yml on master to install pkgdown and rmarkdown from github, and libmagick++-dev from apt
10. pray you haven't forgotten something

[goldingn]

OK, this now auto pushes: https://github.com/goldingn/zoon/commit/3a5498ff347a17188a84d6a34783301b0ef8a377

[goldingn]

However images in the vignettes aren't loading since the HTML is being populated absolute file paths (previously my local files, now relative to the Travis build environment: https://github.com/goldingn/zoon/commit/3a5498ff347a17188a84d6a34783301b0ef8a377#diff-304b279dbd02f2a2d35ad7db3cc07ae1R112)

Need to look into how to make that portable

[goldingn]

also, we can use any one of these themes: https://gallery.shinyapps.io/117-shinythemes/ any favourites @AugustT @GregMci?

[AugustT]

I like the look of Sandstone but defer to the expertise of @GregMci !

[goldingn]

yeah, sandstone is nice and light and fits in with the zoon colour scheme fairly well

[goldingn]

The vignette images issue should be fixed now: https://github.com/hadley/pkgdown/issues/172

[goldingn]

OK, next I'll:

• [ ] use sandstone scheme
• [ ] PR into zoon/master

I'll leave the modules page for now, until we know what's happening with the website