-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
127 lines (85 loc) · 5.75 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
122
123
124
125
126
127
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# repositoryr
<!-- badges: start -->
<!-- badges: end -->
The goal of repositoryr is to provide a step by step guide to creating a R package repository.
## Requirements
- RStudio installed: You will need R and RStudio both installed. You can do so either by:
- Download [RStudio Desktop](https://posit.co/downloads/) OR
- Use [Posit Cloud](https://posit.cloud/) (online) OR
- Install it via Chocolatey (first install R using `choco install r.project` and then RStudio using `choco install r.studio`) OR
- Install it via Homebrew.
## Selecting a package name
Install the package `available` in RStudio using `install.packages("available")`. To find suggestions on valid package names use `available::suggest(text="description of what the package does")`. You can also check whether the package name is available using `available::available("pkgname")`.
![Using available package](inst/images/using_available.png){width=50%}
Alternatively, you can use `pak::pkg_name_check("healthgpsrvis", dictionaries = NULL)`. (Note: To install `pak`, use `install.packages("pak")`).
![Using pak package](inst/images/using_pak.png){width=50%}
## Creating a package
- In RStudio go to File -> New Project -> New Directory -> R Package.
- Write the name of the package and select using renv and initialise git.
- This will create a minimal package structure.
## Create and connect with a GitHub repository
- Create a new repository on GitHub using the same name as the package.
- Set the visibility permissions of this repository as suitable but DO NOT initialise this repository with anything.
- Copy a clone URL of the repository to your clipboard.
More details: [Create and connect a GitHub repo](https://happygitwithr.com/existing-github-last.html#create-and-connect-a-github-repo-without-usethis)
## Connect local repo to GitHub repo
- Click on the “two purple boxes and a white square” in the Git pane.
- Click “Add remote”.
- Paste the GitHub repo’s URL here and pick a remote name, say, `origin` and click “Add”.
- Enter main as the branch name and make sure “Sync branch with remote” is checked and click “Create”.
## Connect local repo to GitHub repo with the command line
- In a shell, run the following (substituting with your URL):
```
git remote add origin https://github.com/ImperialCollegeLondon/repositoryr
git push --set-upstream origin main
```
- You should now be able to see all the project files you committed on the GitHub repo browser.
## Using `devtools`
- Install devtools in RStudio using `install.packages("devtools")`.
- It is a set of packages that support various aspects of package development (it includes the `usethis` package too).
## Using `devtools::check()`
- At this stage, you can try `devtools::check()` to see if there are any issues with the package.
- It should raise an issue about missing/non-standard license in the `DESCRIPTION` file. It will be fixed soon!
## Update `DESCRIPTION` file
- The `DESCRIPTION` file contains the metadata of your package. You can add some descriptive text about your package under `Title` and `Description` fields. You can also fill in the author and maintainer details.
- Manually add BSD-3-Clause license (recommended) first to your repository and then to the `DESCRIPTION` file.
- Run `devtools::check()` to verify if everything works (As of now, it raises a note "Licence stub is invalid DCF.")
## Add R files and corresponding unit tests
- Create a R function file using `usethis::use_r("filename")`.
- A `filename.R` file will be created under the `R/` directory which you can populate.
- Create a corresponding unit test file using `usethis::use_test("filename")`.
- A `test-filename.R` file will be created under the `tests/testthat/` directory where you can add the unit tests.
## Setup documentation
- Use `devtools::document` to set up the documentation for your package.
- Delete the template `R/hello.R` file.
- Now open any other R file (that you created) where you want add the documentation (here it is, the `R/add.R` file).
- Put the cursor somewhere in the function definition. Then do, `Code > Insert roxygen skeleton`. A comment structure should appear above your function, in which each line begins with #'.
- Edit the comments suitably. If a `NAMESPACE` file already exists, please delete it so that it can be automatically generated by `roxygen2`. To do so, run `devtools::document()` this will also create the corresponding `filename.Rd` file in `man/filename.Rd` using `roxygen2`.
## Build a README
- Use `usethis::use_readme_rmd()` to initialize a basic, executable `README.Rmd` file.
- In the `README.Rmd` you can add the purpose of the package, provide installation instructions, and show an example of how the package can be used.
- Remember to render the `README.Rmd` file to make the `README.md` file. You can do this by running `devtools::build_readme()`.
## Create website for your package
- Run `install.packages("pkgdown")`.
- To configure the package to use and deploy pkgdown, run `usethis::use_pkgdown_github_pages()`.
- To preview your site locally before publishing, run `pkgdown::build_site()`.
- This will add the necessary components and sets up GitHub Actions for automatic site building when deploying.
- Your `README.md` becomes the homepage, documentation in `man/` generates a function reference, and vignettes will be rendered into `articles/`.
## Installation
You can install the development version of repositoryr from [GitHub](https://github.com/) with:
``` r
# install.packages("pak")
pak::pak("ImperialCollegeLondon/repositoryr")
```