June 7, 2019 From rOpenSci (https://ropensci.org/blog/2019/06/07/ropensci-docs/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
As part of our continuous effort to improve rOpenSci infrastructure, we are rolling out a new service to automatically build and host documentation for all rOpenSci packages.
We intend this to become the central place to find documentation for rOpenSci packages. We are still rolling this out so not all packages are there yet, but the majority is online now.
What do you need to do as an rOpenSci package maintainer to set this up? Nothing! Each commit to the master branch of your repository automatically triggers a build on our new development server. We do not generate documentation for feature branches and pull requests, only for master.
To check your build logs, click the checkmark behind the commit in your Github repository. There will be a new build status
ropensci/pkgdown that links to the build log for that commit. If the build is failing and you can’t figure out the problem from the logs, please get in touch.
You can also check out the dashboard at https://dev.ropensci.org/ to see status and build histories from all rOpenSci packages.
Our build server uses the standard pkgdown functions to generate the docs; we only override the URL and theming. To test your site locally, install our theme and then render your site with pkgdown:
# Install the rOpenSci theme remotes::install_github("ropensci/rotemplate") # Run in your package directory to build the site: template <- list(package = "rotemplate") pkgdown::build_site(override = list(template = template))
To customize the site you can use any of the standard options in the
_pkgdown.yml file as described in the pkgdown documentation. If you already had a pkgdown site, the system will automatically use your existing
_pkgdown.yml file. You can also have a look at pkgdown configs from other packages.
We hope that the documentation server will become a valuable resource to rOpenSci package users and maintainers. All rOpenSci packages get a canonical URL with a beautiful up-to-date homepage, vignettes, and manual pages, without the need for complicated travis hooks and deploy keys.
Moreover, documentation hosted on
docs.ropensci.org will benefit from the joined pagerank for this domain which boosts the position on Google and other search engines. Hence by centralizing, we simultaneously increase the visibility and reduce maintenance work for rOpenSci packages.
If this works well, we plan to experiment with more new infrastructural services to support rOpenSci ecosystem, with the goal of making it easier to find, use, and maintain our software.