r2readthedocs

Convert R package documentation to a ‘readthedocs’ website.

Why?

Two compelling reasons:

1. R packages are not necessarily self-contained, yet much of the surrounding infrastructure, from CRAN to automatic documentation generators such as pkgdown, presume a package to be a self-contained unit. Any projects requiring greater flexibility must employ alternative documentation systems, for which ‘readthedocs’ (RTD) offers an extremely simple and highly flexible way to embed or enhance package documentation within or alongside almost anything else.
2. ‘readthedocs’ is based on a markup language called ‘reStructuredText’ (.rst), which is more flexible and powerful than the markdown generally used in R packages. Alternatively, yet another form called ‘Markedly Structured Text’ (MyST) can be used instead. The possibility of readily swapping between different markdown parsing systems provide much greater flexibility than available in convention RMarkdown parsers.

Installation

readthedocs requires three python packages which can be installed via your usual python installation method, for example,

pip install sphinx myst_parser sphinx_rtd_theme

This R package can then be installed by running one of the following lines:

remotes::install_github ("ropenscilabs/r2readthedocs")
pak::pkg_install ("ropenscilabs/r2readthedocs")

The package can then loaded for use with

library (r2readthedocs)

How?

For those unfamiliar with ‘readthedocs’ (RTD), we recommend using the rtd_dummy_pkg() function provided with this package, which generates a “skeleton” of a package which can be used to generate an RTD site.

path <- rtd_dummy_pkg ()

Then either using that path to the dummy package, or a local path to a package of your choice, generate an RTD website by running:

r2readthedocs (path)

The RTD website will be automatically opened in your default browser. Most of the content is automatically generated straight from the package documentation, as for a pkgdown website. The primary difference you’ll immediate notice is that the front page is not the package’s README.md document. There are two reasons for this:

1. While markdown pages can be readily inserted into .rst pages, this is not possible for the main page, which must be encoded entirely in .rst form.
2. This package may easily be used to document several packages, or a project of which an actual R package is just one component. Leaving the main page largely unstructured enables ready adaptation to almost any configuration.

The main file controlling the site’s appearance is index.rst, located in a sub-directory of the local path named "docs" - in R terms, at file.path(path, "docs", "index.rst").

Further Information

An RTD site is primarily determined by a few simple files. The r2readthedocs() function initially inserts these files, and then generates the entire site, creating a "docs" sub-directory with a large number of files. The rtd_clean() function can be used to remove all files automatically generated by RTD itself, reducing the files down to the primary set of files controlling the site’s structure and appearance. These are:

1. index.rst responsible for the structure of the main page of the site.
2. conf.py A python script for configuring aspects of the site.
3. requirements.txt containing a list of required python packages, which may be extended as desired.
4. make.bat and Makefile which are responsible for the main build system, and should not be modified. Type make in the local "docs" directory to see a full list of make options.

The main RTD documentation files can be re-generated at any time with rtd_build().