Pkgdown: Co-existence of docs for CRAN and dev version

[topepo]

It would be good to have a convention where the development version of the documentation can be created but prevent these files from being those referenced in index.html (which I would think should be the production version). In other words, can pkgdown facilitate having prod and devel versions of the package docs on the package website?

[jennybc]

@hadley and I just discussed this in our 1-on-1 and I was tasked with opening an issue. Instead I'm going to tweak this one a bit.

Can pkgdown make it easy to flip a switch and go into "dev mode" so that the website can evolve in tandem w/ code in between CRAN releases? Without messing with the official website and confusing users of the released version.

For example, in the pkgdown YAML, can the rendered website be redirected to docs-dev/, for local-only preview and/or hooked up to netlify? So that the developer and keen users can read dev docs but typical user won't end up there by mistake.

This may actually be a case where serving the official website out of a branch is the right move, which I normally dislike.

[hadley]

Would docs/dev be a better location? Then you could also point people to it online.

[jennybc]

Oh, sure, I have no strong opinion about that.

[topepo]

docs/dev works for me.

[pat-s]

Because I just stumbled over it: We have such a concept for mlr. If you replace the devel with release you get the CRAN version (although the html files for this have been created with mkdocs):

http://mlr-org.github.io/mlr/articles/tutorial/devel/bagging.html

You can take a look at our vignettes/ dir how we accomplished that: https://github.com/mlr-org/mlr/tree/master/vignettes.

Basically we just put the last rendered version of the "release" docs into a folder that pkgdown then copies over to docs/.

If something like this exists, it would ofc be nice to a have a switch button on each site that allows to easily switch between the two versions.

[hadley]

Here's my latest thinking, building on @jennybc's idea of a switch. I think all build_() functions should gain a dev argument. When dev = FALSE, pkgdown behaves as currently. When dev = TRUE:

• The destination path gets a dev added to it, e.g. build_home() would now build into docs/dev/index.html by default

• All pages get <meta name="robots" content="noindex"> header so that the development versions never get indexed by a search engine.

• Navbar gains a link back to the released site.

• We somehow style the development pages to make it clear that you're viewing the documentation for the development version

This makes it easy to have a release and development version in parallel, without confusing the user who doesn't want to care about the distinction.

We could automatically detect development mode if the version has four components, and dev_mode: true in _pkgdown.yml.

Other changes:

• clean_site() needs to learn not to delete dev/
• We could be more aggressive about labelling the version on the released homepage (e.g. in the download link).
• If dev/ present, dev = FALSE version needs to automatically add to navbar

[topepo]

Looks good to me. Maybe have an alternate option in yml for devel styling:

template:
  devel_params:

or similar.

Also,knitr has some background variables that boil down to is_html and such. Maybe set a is_devel flag so that the articles can differentiate accordingly.

[jennybc]

Sound good.

I'm trying to think through how one might make changes to the released website. I think you would make a branch with the most recent CRAN release as parent and, e.g., edit the roxygen comment in question and rebuild the site. Then make a PR back to master that would include, e.g., the modified .R file and changes below docs/. You'd probably leave that branch running until the next CRAN release, in case you need to make more changes to the released site.

[hadley]

Right - and you can make the branch from the release tag, if needed.

[hadley]

A few revisions as I work on this:

• Displaying the version in the nav bar seems like a very good idea, and makes it possible to highlight the fact that you might be looking at a site that corresponds to a development version of the site

• Passing dev = TRUE through every function is going to be tedious to implement, so I think it'll be easier to simply set in _pkgdown.yml (and you can always override with override)

• I'm no longer sure about putting links between the site versions in the navbar. I think possibly links on the homepage will be adequate - I _think_ it will be hard to accidentally end up in the wrong place.

[hadley]

The development mode of a site controls four main things:

• Where the site is built
• The colour of the package version in the navbar
• The optional tooltip associated with the version
• The indexing of the pages by search engines.

There are currently three possible development modes:

• release: site written to docs/, the version gets the default colouring,
  and no message.

• development: written to docs/dev/, the version gets a danger label, and
  message stating these are docs for an in-development version of the package.
  The noindex meta tag is used to ensure that these packages are not
  indexed by search engines.

• unreleased: the package is written to /, the version gets a "danger"
  label, and the message indicates the package is not yet on CRAN.

The default development mode is "release". You can override it by adding a new development field to _pkgdown.yml, e.g.

development
  mode: development

You can also have pkgdown automatically detect the mode with:

development
  mode: auto

In this case the mode will be automatically determined based on the version number:

• 0.0.0.9000 -> unreleased
• four components -> development
• everything else -> release

There are three other options that you can control:

development:
  destination: dev
  version_label: danger
  version_tooltip: "Custom message here" 

destination allows you to override the default subdirectory used for the development site; it defaults to dev/. version_label allows you to override the style used for development (and unreleased) versions of the packgae. It defaults to "danger", but you can set to "default", "info", or "warning" instead. (The precise colours are determined by your bootstrap theme, but become progressively more eye catching as you go from default to danger). You can also choose to override the version_message.

[batpigandme]

Would this mean disabling the traceback for vignettes and/or object documentation for release mode? Depending on the time between releases, a file could change quite a bit— or even just little things, which could be _slightly_ confusing to new user/contribs.

[hadley]

I don't think so; at some people are going to have to grapple with the fact that stuff changes in between releases and what they see locally might be different to what's on github.

[jennybc]

It does create the possibility that the source document for a page in the pkgdown site does not exist in current master branch. To be clear, I still really want this to happen!

But we might need canned advice re: trying to locate the thing you want to change in the dev site if clicking on the alleged "Source" file does not go well.

[jennybc]

unreleased: the package is written to /

I don't follow this. Is it a typo?

[hadley]

Yes, should be docs/!

[hadley]

No links between the versions yet. I'm going to need to mull on that.

[pat-s]

A few thoughts on this:

• To work well with automated deployment via CI, release should copied and not rebuild if development = devel.
• If there is no release it needs to be build even when development = devel as otherwise serving through Github pages will not work as docs/ will not contain a index.html but just a dev/ folder.
• I think it would be good if build_site(dev=T) is the default as the release version only needs to be build for every release while the dev version includes the most recent changes and needs to be build more often. Again, if there is no release it should be triggered unless one sets experimental (= no release avail).

[hadley]

I think you've missed that dev is a subdirectory of docs. Take a look at the more polished description in build_site().

[pat-s]

Nono, that's perfectly clear :) It just results in this: https://github.com/pat-s/mlr/tree/gh-pages when using an automatic deployment. This works as expected from the CI point of view but..

... it also means that https://pat-s.github.io/mlr/dev/ is valid but https://pat-s.github.io/mlr is 404.
Of course you could just link to mlr/dev and solve the problem but I would say there should be a also a release if dev exists?

In the example shown I am serving from the gh-pages branch rather than docs/' from themaster` branch but this does not make a difference.

[batpigandme]

If I'm understanding things correctly, release is built from foo/docs and dev from food/docs/dev. So, the gh-pages branch should work, it's just a matter of a missing docs/ folder…

Edit: or your gh-pages would have the contents of docs _and_ the dev/ dir as well.

[pat-s]

If I'm understanding things correctly, release is built from foo/docs and dev from food/docs/dev. So, the gh-pages branch should work, it's just a matter of a missing docs/ folder…

I know. I think my communication skills are lacking here :sweat_smile:
I state that there should be a docs/ (corresponding to a release site) if docs/dev exists.
build_site() would optimally be able to detect if there is a valid "release" site within docs/ and

• build one if not
• if there is one, only rebuild it if explicitly stated (e.g. when releasing a new version)

[hadley]

I don't see how pkgdown can do this because it would have to check out the release commit. It's your responsibility to manage this. If you use mode: auto and do all the building with a CI, this should just work.