Convert R package documentation to a ‘readthedocs’ website.
Two compelling reasons:
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.
.rst), which is more flexible and powerful than the
markdowngenerally used in R packages.
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:
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. This is because, which
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. The front page of any site generated with the
r2readthedocs() function will retain this general form, which can then be readily adapted as desired. The main file controlling the site’s appearance is
index.rst, located in a sub-directory of the local
"docs" - in R terms, at
file.path(path, "docs", "index.rst").
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:
index.rstresponsible for the structure of the main page of the site.
conf.pyA python script for configuring aspects of the site.
requirements.txtcontaining a list of required python packages, which may be extended as desired.
Makefilewhich are responsible for the main build system, and should not be modified. Type
makein the local
"docs"directory to see a full list of
The main RTD documentation files can be re-generated at any time with