Tuesday, November 29, 2022 From rOpenSci (https://ropensci.org/blog/2022/11/29/postdoc-docs/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
We released two new packages that we are using in r-universe to render package documentation: postdoc and prismjs.
The goal of postdoc is very simple: generate beautiful single-page package manuals in HTML format. Postdoc uses our prismjs and katex packages for server-side highlighting and math. Try it yourself:
# Download and install postdoc in R install.packages('postdoc', repos = c('https://ropensci.r-universe.dev','https://cloud.r-project.org')) # Generate a manual for 'jsonlite' html <- postdoc::render_package_manual("jsonlite", ".") utils::browseURL(html)
We have recently started building the reference manuals for each package r-universe: for packages that have had an update in the past 10 days, the reference manual is now linked from the package homepage on r-universe.dev. All packages in in r-universe gets rebuilt at least once per month, so soon all packages should have the manual. Postdoc reference manuals for base-R packages can be found here.
Below some random examples of refence manuals from popular packages to get an impression:
https://r-universe.dev/manuals/Matrix.html(lots of math)
There are many ways to browse R package documentation, such as a pkgdown site or the
? command in R. But one of the simplest ways, that is available for all packages, is viewing the PDF reference manual in your browser from CRAN or r-universe.
The reference manual gives an overview of everything in the package, nicely indexed and searchable within a single document. Because it is just one file, it is easy to share and archive a particular version of the manual that belongs with a given version of the package. This makes a reference manual a useful resource, even for packages that have e.g. a pkgdown site.
Unfortunately, base-R can only generate reference manuals in PDF format. This is a long standing issue: Jonathan Godfrey published an article in the R journal 10 years ago called Statistical Software from a Blind Person’s Perspective in which he explains that the PDF format is terrible for him because it is not machine readable and hence does not work well with screen readers. Earlier this year he reiterated some of these points on the mailing list, suggesting to switch to HTML where possible.
Besides accessibility, there are many other reasons HTML is a far superior format these days. Because it is text-based, it does not require special tooling to generate (such as latex) or a special viewer (e.g. mobile devices often don’t have a pdf reader). With some CSS we can apply custom styling, without cluttering the content. In summary, some benefits of postdoc HTML reference manuals:
Math rendering in HTML with katex or mathjax is these days on-par with LaTeX, and syntax highlighting far superior. Generally HTML documents are much more readable both for humans and machines. The latter will not only help screen-readers, but also make the documentation visible to search engines.