The goal of repositoryr is to provide a step by step guide to creating a R package repository.
-
RStudio installed: You will need R and RStudio both installed. You can do so either by:
- Download RStudio Desktop OR
- Use Posit Cloud (online) OR
- Install it via Chocolatey (first install R using
choco install r.project
and then RStudio usingchoco install r.studio
) OR - Install it via Homebrew.
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")
.
Alternatively, you can use
pak::pkg_name_check("healthgpsrvis", dictionaries = NULL)
. (Note: To
install pak
, use install.packages("pak")
).
- 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 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
- 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”.
- 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.
- 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).
- 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!
- The
DESCRIPTION
file contains the metadata of your package. You can add some descriptive text about your package underTitle
andDescription
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.”)
- Create a R function file using
usethis::use_r("filename")
. - A
filename.R
file will be created under theR/
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 thetests/testthat/
directory where you can add the unit tests.
- 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 byroxygen2
. To do so, rundevtools::document()
this will also create the correspondingfilename.Rd
file inman/filename.Rd
usingroxygen2
.
- Use
usethis::use_readme_rmd()
to initialize a basic, executableREADME.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 theREADME.md
file. You can do this by runningdevtools::build_readme()
.
- 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 inman/
generates a function reference, and vignettes will be rendered intoarticles/
.
You can install the development version of repositoryr from GitHub with:
# install.packages("pak")
pak::pak("ImperialCollegeLondon/repositoryr")