Update website using pkgdown

[dfalster]

Pkgdown packages supercedes staticdocs.

Detailed instructions here: http://hadley.github.io/pkgdown/articles/pkgdown.html

Need to consider whether to keep website on a gh-pages branch or move to main repo, as send to be now common practice. Downside is increasing size of the repo.

[dfalster]

Currently we use the staticdocs package to generate documentation. It looks like hadley has shifted focus to the newer pkgdown package but need to confirm. If so we'd be better off going with that.

Need to review if pkgdown can publish to gh-pages branch, as the default is to push to a docs folder on same branch. The tow issues for us are

• our docs are slow to generate (vigenttes take an hour)
• our docs are potentially very large so may want to store on a separate branch to kepp package size small
• we already have a "docs" folder, so may need to rename.

[dfalster]

Looks like staticdocs now redirects to pkgdown, though there's a fork still floating about at https://github.com/jcheng5/staticdocs

[dfalster]

Also want document how all of this is setup!

[johnWilshire]

As a start I have renamed the docs directory to pre_docs but am very open to renaming it to something else.

I am running into an issue where when I run the (modified) make

vignettes:
    (cd pre_docs; remake install_vignettes)

pkgdown: vignettes
    Rscript -e "library(methods); pkgdown::build_site()"

I get the pandoc error in the build_home section of build_site:

sh: +RTS: command not found
Error: pandoc document conversion failed with error 127
Execution halted
make: *** [pkgdown] Error 1

The same thing happens when I run it from R from the terminal.

But it seems to work fine when I run pkgdown::build_site() from Rstudio (???)

So this is something that I will need to work out in order to get back to the make workflow.

The vignettes aren't being built though because the vignettes folder is empty, despite being able to run remake fine within the pre_docs (and immediately thanks for sharing your docs with .remake).

Was there a step that copied the vignettes back into the vignettes from the (old) docs folder? maybe somewhere in static docs? when I copy the contents of the vignettes folder from pre_docs into the new folder pkgdown seems to build them fine as articles but the titles need tweaking.

BTW that fork of staticdocs doesn't have a build_site() function, agrueneberg/staticdocs does though.

[dfalster]

Great start.

Re pandoc: rstudio includes pandoc, but could it be that R from terminal can't find it? I think I have paid installed elsewhere too. Otherwise make sure rstudio version is in your path?

Re vignettes: make vignettes should be both building and copying them across. This calls a function in 'pre_docs/R/vignettes.R' called 'build_vignettes' which should copy. But I just noticed that on my machine it copies them into 'pre_docs/vignettes' which is a symlink to 'vignettes'. Maybe on yours the symlink doesn't exist? Perhaps better to copy directly then?

[johnWilshire]

Ah Thank you that solved it! I must not have reinstalled pandoc when setting up my laptop.

I tried copying directly back a folder into vignettes at first but I ran into issues with the pre_docs/remake.yml files copying to target_name which was vignettes/foo/bar.md a lot of the time, instead of trying to sort all of these out I force the creation of the symlink in the make file. In d7f047b you can run:

make pkgdown to make the pkgdown site, the site should open in your web browser when built.

TODO:

• Styling if you want (It is a bit grey at the moment)
• merge branch with master branch, read site from docs and close the ghpages branch

[dfalster]

Thanks John.

I'd actually like to keep the website on the gh-pages branch. This is because the articles are substantial and with all the figures will quickly explode the size of the main git repo. (IMO this is a downside of the pkgdown model). Sorry to be demanding, but I'd also like you to rewrite the history to remove the committed docs from the develop branch history as well. (otherwise the 3Mb of files just committed add 3Mb to the git history).To do this:

First undo the last commit on develop

reset --soft HEAD^

Then make various fixes (unstage docs, add docs folder to gitignore) etc, then make a new commit

then do a force push to overwrite the history

git push -f origin develop

(ordinarily force pushes are discouraged, except when you definitely want to rewrite history) That should change the most recent commit on develop to something just involving changes to the make file etc.

Some other requests:

• Can we rename pre_docs to inst/docs?
• Any styling suggestions for pkgdown site are very welcome!
• Can pkgdown also support the pdf docs, e.g. demography.pdf and physiology.pdf?
• Can you add a bit more to commit messages, and reference issu numbers, e.g.:

Updating to use pkgdown for website construction

For #185
Previously using staticdocs to build website but that not longer supported
pkgdown builds into the docs folder, so content previously at docs was moved to pre_docs

[johnWilshire]

No worries! I agree, I never understood why the docs folder had to be in the master branch in pkgdown, if the user really wants a local copy of the html docs then they have the tools to build them, or can just clone the gh-pages branch right?

We should be able to use make website to push the now gitignore'd /docs where the pkgdown site is. folder to the gh-pages branch.

I am not sure what you mean by pkgdown support for pdf docs, but we could have something in the makefile that copies the pdf's over to the docs folder then we can link to them from the pkgdown site?

I ended up choosing cosmo as it is very similar to the current staticdocs site that you have.

Thanks I can see why more detailed commit messages would be a good habit to get into.

[dfalster]

Great, that all sounds good, thanks!

I'll look into converting the pdf docs to html. Main hassle will be getting the equation referencing to work nicely.