Undoubtedly, a website is a good addition to a project, but to build it - Is it worth the hassle?
Well thankfully for R package developers, the pkgdown package provides an easy and convenient way to craft a website from scratch, or with auto-generated elements (such as the index being curated from your GitHub readme, or the articles being derived from your vignettes). The former approach would require a bit of additional digging from the manuals in order to comprehend how to fully customize everything, but the latter is pretty simple to start with. The pkgdown generated website for the official GitHub repository enacted as a quick reference (being a nice example in itself) for building mine.
Brief Overview
The home page is built upon a typical index.md, so as to avoid reflecting a few points in the readme (nearly the same), and to have a different source altogether, or in general.
There is a ‘Reference’ section which as the name suggests, provides ready reference to the functions in the package. It fetches data from the manuals or the /man directory (just like rdrr.io does), with content from my roxygen-scripted documentation. Apart from creating that in my pkgdown.yml, I intend to modify the navbar structure and incorporate a few more sections over time, but it’s not a priority now.
Regarding the theme, I’m going with sandstone via the bootswatch template. Lastly, the website is being hosted via GitHub Pages, with the build source being the /docs directory.
Articles
With a bit of research/fact-gathering and testing, a few vignettes were created using rmarkdown and knitr for most of the functions mentioned in this list, and corresponding articles were generated using pkgdown, which can be accessed from the dropdown menu ‘articles’ in the navigation bar of the website.
I intend to include the remaining functions as well, but I’m facing some issues with them at present, so will upload the vignettes when they are resolved. If you have a package with an algorithm that you would want to test the computational complexity of, please feel free to ping me up on my mailbox, or post it as an issue to testComplexity!
Search
Thanks to DocSearch from Algolia, an autocomplete search functionality could be incorporated into the website’s navigation bar, which is generously provided by them for free. Internally, a crawler is run on their infrastructure at a 24-hour interval which follows every link in the website and extracts content from every page it traverses. The collected data is pushed into an Algolia index, binding it to the search input provided by the user, and correspondingly displaying the matched results in a dropdown UI. (with neat highlighting :)
In some scenarios, you’ll need to incorporate a JavaScript snippet externally, but for my case, it was as simple as dropping the API key & index name in my pkgdown.yml. (customer support is good, but expect a few days of waiting for the credentials)
A few more changes are anticipated following the inclusion of development mode attributes and the ‘News’ section (enlisting what’s new or updated for different numbers signifying major.minor.patch.dev - yes, the version!), after the CRAN release.
| Anirban | 08/10/2020 |