Repository files navigation

Convert R package documentation to a‘readthedocs’ website.

Two compelling reasons:

1. R packages are not necessarily self-contained, yet much of thesurrounding infrastructure, from CRAN to automatic documentationgenerators such aspkgdown, presumea package to be a self-contained unit. Any projects requiringgreater flexibility must employ alternative documentation systems,for which‘readthedocs’ (RTD) offers anextremely simple and highly flexible way to embed or enhance packagedocumentation within or alongside almost anything else.
2. ‘readthedocs’ is based on a markuplanguage called‘reStructuredText’(.rst),which is more flexible and powerful than themarkdown generallyused in R packages. Alternatively, yet another form called‘Markedly Structured Text’(MyST)can be used instead. The possibility of readily swapping betweendifferent markdown parsing systems provide much greater flexibilitythan available in conventionRMarkdown parsers.

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

pipinstallsphinxmyst_parsersphinx_rtd_theme

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

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

The package can then loaded for use with

library (r2readthedocs)

For those unfamiliar with‘readthedocs’(RTD), we recommend using thertd_dummy_pkg() function provided withthis package, which generates a “skeleton” of a package which can beused to generate an RTD site.

path<- rtd_dummy_pkg ()

Then either using thatpath to the dummy package, or a local path to apackage 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 packagedocumentation, as for apkgdown website.The primary difference you’ll immediate notice is that the front page isnot the package’sREADME.md document. There are two reasons for this:

1. Whilemarkdown pages can be readily inserted into.rst pages,this is not possible for the main page, which must be encodedentirely in.rst form.
2. This package may easily be used to document several packages, or aproject of which an actual R package is just one component. Leavingthe main page largely unstructured enables ready adaptation toalmost any configuration.

The main file controlling the site’s appearance isindex.rst, locatedin a sub-directory of the localpath named"docs" - in R terms, atfile.path(path, "docs", "index.rst").

An RTD site is primarily determined by a few simple files. Ther2readthedocs() function initially inserts these files, and thengenerates the entire site, creating a"docs" sub-directory with alarge number of files. Thertd_clean() function can be used to removeall files automatically generated by RTD itself, reducing the files downto the primary set of files controlling the site’s structure andappearance. These are:

1. index.rst responsible for the structure of the main page of thesite.
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 andMakefile which are responsible for the main buildsystem, and shouldnot be modified. Typemake in the local"docs" directory to see a full list ofmake options.

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