Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/evamaerey/readme2pkg.template


https://github.com/evamaerey/readme2pkg.template

Last synced: 11 days ago
JSON representation

Awesome Lists containing this project

README 

        
---

output: 

  github_document:

    toc: TRUE

    toc_depth: 2

---



```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  eval = T

)

```



# *To the reader* 



Welcome to the R package building helper *readme2pkg.template*!



Below, is a readme that provides steps for building a package.  This readme acts as a worksheet, checklist, and control document as functions used in package building are included within and can be used in advancing development.  



We'll use the `{readme2pkg}` helper package to send code chunks to different directories in the package.  



To install `{readme2pkg}`:



```



remotes::install_github("EvaMaeRey/readme2pkg")



```



# Part 0. Proposal



Proposing the {xxxx} package! 🦄 



The goal of {xxxx} is to make ... easier.



Without the package, we live in the effort-ful world that follows 🏋:



```{r}

x <- 4



2*x



```



  

With the {xxxx} package, we'll live in a different world (🦄 🦄 🦄) where the task is a snap 🫰: 



Proposed API:



```



library(xxxxx)



xxxxx::times_two(x = 4)



```



# Part I. Work out functionality  🚧 ✅ 



Here is a function that will do some work...



```{r times_two}

times_two <- function(x){

  

  x*2

  

}

```



## Try it out



```{r}

times_two(4)

```



# Part II. Packaging and documentation  🚧 ✅ 



## Phase 1. Minimal working package



### Bit A. Created package archetecture, running `devtools::create(".")` in interactive session. 🚧 ✅



```{r, eval = F}

devtools::create(".")

```



### Bit B. Managing [dependencies](https://r-pkgs.org/dependencies-in-practice.html) if they exist 🚧 ✅



Dependencies -- use of non-base R functions within your function -- must be declared in your package.  



This means ...



1. you'll use the `::` notation, e.g. `package::function()` in your functions when you use another package's functions.  

2. you'll document package dependencies to your DESCRIPTION

file -- this can be done automatically with `usethis::use_package`, the example is the case where ggplot2 is a dependency:



```{r, eval = F}

usethis::use_package("ggplot2")

```



### Bit C. Moved functions [R code folder](https://r-pkgs.org/code.html)? 🚧 ✅



Use new {readme2pkg} function to do this from readme...



```{r, eval = F}

readme2pkg::chunk_to_r(chunk_name = "times_two")

```



### Bit D. Run [`devtools::check()`](https://r-pkgs.org/whole-game.html#check) and address errors. 🚧 ✅



```{r, eval = F}

devtools::check(pkg = ".")

```



devtools check will document the functions for you. 



### Bit E. [Install](https://r-pkgs.org/whole-game.html#install) and restart your brand new package!! 🚧 ✅



```{r, eval = F}

devtools::install(pkg = ".", upgrade = "never")

```



### Bit F. Write traditional README that uses built package (also serves as a test of build). 🚧 ✅ 



The goal of the {xxxx} package is to ...



Install package with:



```

remotes::install_github("GithubCoolUser/mypacakge")

```



Once functions are exported you can remove go to two colons, and when things are are really finalized, then go without colons (and rearrange your readme...)



```{r, eval = F}

library(mypackage)  ##<< change to your package name here

mypackage:::times_two(10)

```



### Bit G. Add [lifecycle badge](https://r-pkgs.org/lifecycle.html) (experimental) 🚧 ✅



```{r, eval = F}

usethis::use_lifecycle_badge("experimental")

```



### Bit H. Compile README.Rmd 🚧 ✅



### Bit I. Push to github. 🚧 ✅



RStudio: Console/Terminal/RMarkdown/Jobs:



Terminal -> git add . -> git commit -m "first commit" -> git push



## Phase 2: Listen & iterate 🚧 ✅



Try to get feedback from experts on API, implementation, default decisions, names.  Is there already work that solves this problem? 



> "Hey Jordan, I know you are an expert in multiplication methods.  I was wondering if you'd have a look at the motivation and functionality in my development {times.two} package found at github.com/myusername/times.two"



> "Hey Ella, I know you've done great worked on {times.three}.  I think my new project does something similar in terms API.  I was wondering if you'd have a look at the implementation. Code can be found in github.com/myusername/times.two "



## Phase 3: Settling and testing 🚧 ✅ 



In this phase you should start settling on function and argument names, decide which ones will be exported, and make those functions more robust and usable with examples, tests, messages and warnings.



### Bit A. Added a description and author information in the [DESCRIPTION file](https://r-pkgs.org/description.html) 🚧 ✅



### Bit B. Added [roxygen skeleton](https://r-pkgs.org/man.html)? 🚧 ✅



Use a roxygen skeleton for auto documentation and making sure proposed functions are *exported*. (in RStudio 'Code -> insert Roxygen Skeleton) Generally, early on, I don't do much (anything) in terms of filling in the skeleton for documentation, because things may change.



### Bit C. Chosen a [license](https://r-pkgs.org/license.html)? 🚧 ✅



```{r, eval = F}

usethis::use_mit_license()

```



### Bit D. Settle on [examples](https://r-pkgs.org/man.html#sec-man-examples).  Put them in the roxygen skeleton and readme. 🚧 ✅



### Bit E. Written formal [tests](https://r-pkgs.org/testing-basics.html) of functions and save to test that folders 🚧 ✅



That would look like this...



```{r test_calc_times_two_works, eval = F}

library(testthat)



test_that("calc times 2 works", {

  expect_equal(times_two(4), 8)

  expect_equal(times_two(5), 10)

  

})

```



```{r, eval = F}

readme2pkg::chunk_to_tests_testthat("test_calc_times_two_works")

```



### Bit F. Check again. Addressed notes, warnings and errors. 🚧 ✅



```{r, eval = F}

devtools::check(pkg = ".")

```



## Phase 4. Promote to wider audience...  🚧 ✅ 



### Bit A. Package website built? 🚧 ✅



### Bit B. Package website deployed? 🚧 ✅



## Phase 5: Harden/commit: Submit to CRAN/RUniverse 🚧 ✅ 



# Appendix: Reports, Environment



## Description file complete?  🚧 ✅



```{r, eval = F}

readLines("DESCRIPTION")

```



## Environment  🚧 ✅



Here I just want to print the packages and the versions



```{r}

all <- sessionInfo() |> print() |> capture.output()

all[11:17]

```



## `devtools::check()` report



```{r, eval=F, error = T, results="hide", warning=F}

devtools::check(pkg = ".")

```



## Package directory file tree



```{r}

fs::dir_tree(recurse = T)

```