Pkgdown: Document and export deploy_local()

[AliciaSchep]

The deploy_site_github function is configured to be specific to running on travis environment. IMO it is nice to also have option to deploy to gh-pages branch locally instead of only on travis (and having the clone to temp directory & build there & push all automated in a function is much smoother than trying to do those steps manually).

I wrote a little modification of the function to enable such local deployment: gist. It enables you to preview the site, and then choose to push to gh-pages.

Wondering if y'all might consider adding such functionality to pkgdown, either enabling the package's deploy_site_github function to also run locally or adding another function specific to local use?

[jayhesselberth]

I'm not sure what added functionality you're proposing. You can already preview the site locally with pkgdown::build_site(). If you add the docs/ directory to your .gitignore, these builds will stay local.

[AliciaSchep]

Sorry for the potential misdirection, the mention of previewing wasn't super relevant to the main functionality I was talking about.

The capability desired is to build the site & push it to gh-pages branch. Exactly what deploy_site_github does but that I can do it on my computer instead of it only working on travis**.

If I build the site and add docs/ to .gitignore the problem is that as you say, the build will stay local... I am looking to build locally and deploy.

Why pushing to gh-pages and not just pointing github to 'docs' folder? Because even though I am using github to host the pages, I don't really want these artifacts in my git repo. I don't want to have to worry about merge conflicts in the rendered artifacts or to look at diffs... shoving these artifacts into their own branch is a way of basically freeing the main branches of them but still having them on github and available for serving via Github Pages. (Ideally I'd also want to obliterate the history of gh-pages as #962 requests, although it seems that currently isn't compatible with how different site versions are handled)

**Looking more closely at the code it seems like if I set my local env up correctly and pass the right arguments to deploy_site_github that I might already be able to call the function as is, however the documentation is pretty direct in saying "it should not be called locally", and also I probably wouldn't want to alter the "~/.ssh/id_rsa" file locally which is what the function does.

[jayhesselberth]

I think we could just export and document pkgdown::deploy_local() for this purpose:

https://github.com/r-lib/pkgdown/blob/0b2c27d41b869ac31b6a46815940f55b12f6171f/R/deploy-site.R#L101

You could test whether this works by running pkgdown:::deploy_local().

[AliciaSchep]

Yes, I think exporting pkgdown:::deploy_local would address this use case perfectly!

(I had originally tinkered with a variant of that function (the gist linked in initial post), but I think none of the changes were actually needed for the main functionality... have now tested out pkgdown:::deploy_local(repo_slug = "ropensci/iheatmapr") and it worked fine)

[noamross]

I also would like to see export and documentation of deploy_local() including perhaps renaming it, with an eye towards use in non-Travis CI systems. deploy_site_github() is written specifically for Travis-CI's configuration of storing SSH keys and the names of its environment variables, while other systems do so differently.

Here is an example of using deploy_local() on CircleCI: https://github.com/ecohealthalliance/citesdb/blob/master/.circleci/config.yml#L33-L42

[hadley]

Proposal:

• deploy_site_github() -> deploy_travis() (with deprecation warning)
• deploy_local() -> deploy_github()
• Installation code moves into deploy_github()

[maxheld83]

don't want to sidetrack this conversation, but since @hadley asked how pkgdown might be used in GitHub actions (which I'm currently working on), here are my thoughts.

TL;DR: ghactions follows a fairly strict separation of concerns, and only ever uses pkgdown::build_site().

• So far, I don't see a need to do any of the actual deployment work in R, let alone in pkgdown.
  I've build/wrapped some language-agnostic lean actions (in bash), which allow publishing arbitrary directories of arbitrary stuff to GitHub Pages, Netlify, Firebase or even rsync.
• There's also an action to just run pkgdown::build_site().
• For more convenient use, these and other actions are wrapped by ghactions to provide templates for a quick start in the style of usethis::use_travis().
  The package also provides helpers for setting up auth etc., much like travis::use_travis_deploy().

You can see this in action in my .github/main.workflow, where I'm dogfooding this.

I'll think about adding some of the fancier stuff pkgdown does (pkgdown-specific commit messages etc.) to ghactions, but this would presumably just happen in the pkgdown action (-> https://github.com/r-lib/ghactions/issues/202).

[maxheld83]

as for function names, I'd suggest deploy_x_y(), where x is the target (GitHub pages, Netlify, etc.), and y is the CI/CD compute environment (Travis, local, ...).

• deploy_site_github() -> deploy_ghpages_travis().
• deploy_local() -> deploy_ghpages_local().

My concerns with deploy_travis() vs deploy_github() are:

• one (travis) is a CI/CD service via which we'd deploy
• the other (github pages) is a deploy target.

So it's a bit of a confusing dichotomy.

Also, with GitHub actions (and possibly GitHub-native CI/CD) on the horizon deploy_github() might be confusing in itself (is this referring to GitHub pages? actions? CI?).

[maxheld83]

come to think of it, I'm duplicating most of the code in deploy_* as part of GitHub actions bash scripts, and it'd be happy to try and factor it out -> https://github.com/r-lib/pkgdown/issues/1038

[jayhesselberth]

I'm in favoring of holding off on this as it sounds like gh actions will be a better path forward, once it's widely available.

[hadley]

Closing since we now have deploy_to_branch().