All rOpenSci packages now have a pkgdown website that’s updated with each commit to master. With the way the system works at the moment, we cannot use pkgdown’s “auto” mode (creating a website for the released version at the root, and one for the dev version under dev/).
The website might document behaviors/functions that are not released on CRAN. Should this be avoided (by using a dev branch until release)? If not, how to make it clear?
There’s a version badge on all pkgdown websites (at the top left of drake website for instance) and the homepage can feature a CRAN version badge. Maybe this + the changelog is enough?
By using a lifecycle badge in the function? (see drake reference)
For mlr3 we are using the auto mode via CI deployed pkgdown builds.
The version in the DESCRIPTION file decides whether the site is deployed to . or ./dev.
If it contains a .9000 it will be dev, otherwise it will be deployed to the “release” page.
By default the CRAN release site is shown to the user.
This approach only works if one sticks to the model of strictly using .9000 versions for dev cycles and only do different for that one commit which should reference the latest CRAN release.
We added some links to the README (release / dev) which link both versions.
It would probably be better to have them sticky in the menu bar.
My ideal scenario would be that we support multiple versions on our docs server (e.g., current CRAN version [i.e., should be the same as most recent git tag], and perhaps current dev version) - but we don’t support that right now. readthedocs does this nicely.
@sckott What is your opinion on the dev/release approach we use in mlr? If the switch would be accessible in a static way in the menubar I’d be more happy but I currently have no resources for this.
Also text would take up valuable space in the menubar - maybe an icon in combination with a text on hover stating “switch to dev/release”.
I like it, its better than what we currently have at least.
I think it’d be powerful to have a way to switch versions of the docs when a user is on any particular page of the docs, eg., for a certain function, as they may want to look at what changed between two versions of the package - but it doesn’t seem like that’s possible with the pkgdown auto thing you mentioned
This is not currently possible, correct. With a bit HTML skills one could insert this into the rotemplate by checking the current url and either insert/remove dev when a user clicks on it (assuming its a clickable navbar item).
But yeah, nothing that can be done in a few minutes.
