-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
121 lines (94 loc) · 4.88 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
---
title: "r2readthedocs"
output:
md_document:
variant: gfm
rmarkdown::html_vignette:
self_contained: no
---
<!-- badges: start -->
[](https://github.com/ropenscilabs/r2readthedocs/actions)
[](https://github.com/ropenscilabs/r2readthedocs/actions?query=workflow%3Apkgcheck)
[](https://codecov.io/gh/ropenscilabs/r2readthedocs)
[](https://www.repostatus.org/#concept)
<!-- badges: end -->
# r2readthedocs
Convert R package documentation to a ['readthedocs'](https://readthedocs.org/) 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`](https://pkgdown.r-lib.org/),
presume a package to be a self-contained unit. Any projects requiring
greater flexibility must employ alternative documentation systems, for which
['readthedocs'](https://readthedocs.org/) (RTD) offers an extremely simple and
highly flexible way to embed or enhance package documentation within or
alongside almost anything else.
2. ['readthedocs'](https://readthedocs.org/) is based on a markup language
called ['reStructuredText'
(`.rst`)](https://docutils.sourceforge.io/docs/user/rst/quickref.html),
which is more flexible and powerful than the `markdown` generally used in
R packages. Alternatively, yet another form called ['Markedly Structured
Text' (MyST)](https://myst-parser.readthedocs.io/en/latest/index.html#) 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,
```{python, eval = FALSE}
pip install sphinx myst_parser sphinx_rtd_theme
```
This R package can then be installed by running one of the following lines:
```{r remotes, eval = FALSE}
remotes::install_github ("ropenscilabs/r2readthedocs")
pak::pkg_install ("ropenscilabs/r2readthedocs")
```
The package can then loaded for use with
```{r library, eval = FALSE}
library (r2readthedocs)
```
## How?
For those unfamiliar with ['readthedocs'](https://readthedocs.org/) (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.
```{r rtd-dummy, eval = FALSE}
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:
```{r rtd-run, eval = FALSE}
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`](https://pkgdown.r-lib.org/) 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()`.