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.lite

All the readme2pkg template stuff, without all the explanation
https://github.com/evamaerey/readme2pkg.template.lite

Last synced: 11 days ago
JSON representation

All the readme2pkg template stuff, without all the explanation

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,

  error = T

)

```



# *To the reader*



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



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 `{knitrExtra}` helper package to send code chunks to different directories in the package.



To install `{knitrExtra}`:



```



remotes::install_github("EvaMaeRey/knitrExtra")



```



# Part 00. Proposal



*Note: This README walks through package rational and contains the code that defines proposed package functions and in addition to first-cut testing. [TLDR - Jump to traditional readme content](#traditional-readme)*



Proposing the {xxxx} package! 🦄 



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



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



```{r}

library(ggplot2)



ggplot(data = cars) + 

  aes(speed) + 

  geom_histogram(fill = "green")  

```



  

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



Proposed API:



```



library(greenhistogram)



ggplot(data = cars) + 

  aes(speed) + 

  geom_green_histogram()   # new function!

  

```



```{r exit0, eval = F}

# for quick knit (exiting early) change eval to TRUE

# fs::dir_tree(recurse = T)

knitr::knit_exit()

```



# Part 0. Lay out package infrastructure



```{r interactive1, eval = F}

devtools::create(".")

```



# Part I. Work on functionality  🚧 ✅ 



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



```{r geom_green_histogram}

geom_green_histogram <- function(...){

  

  geom_histogram(fill = "green", ...)

  

}

```



## Try it out



```{r}

library(ggplot2)



ggplot(data = cars) + 

  aes(speed) + 

  geom_green_histogram()

```



# Part II. Packaging and documentation  🚧 ✅ 



## Phase 1. Minimal working package



To build a minimal working package, 1) we'll need to document dependencies 2) send functions to .R files in the R folder, 3) do a package check (this will A. Document our functions and B. this will help us identify problems - for example if we've failed to declare a dependency) and 4) install the package locally.  



Then we'll write up a quick advertisement for what our package is able to do in the 'traditional readme' section.  This gives us a chance to test out the package.



```{r}

### Bit 2a: in the function(s) you wrote above make sure dependencies to functions using '::' syntax to pkg functions 

usethis::use_package("ggplot2") # Bit 2b: document dependencies, w hypothetical ggplot2

```



```{r}

# Bit 3: send the code chunk with function to R folder

# knitrExtra::chunk_names_get()

knitrExtra:::chunk_to_r(chunk_name = "geom_green_histogram") 

```



```{r interactive2, results = "hide", eval = F}

# Bit 4: document functions and check that package is minimally viable

devtools::check(pkg = ".")  



# Bit 5: install package locally

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

```



# Traditional README



### Bit 7. 



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}

rm(list = ls())

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



# some demonstration code here, accessing function w ::: syntax



```



```{r exit1, eval = T}

# for quick knit (exiting early) change eval to TRUE

# fs::dir_tree(recurse = T)

knitr::knit_exit()

```



# Bit 8: Compile readme



# Bit 9: Push to github (if your package is connected)



# Bit 10: listen and iterate



## Phase 3: Settling and testing 🚧 ✅ 



### 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) for exported functions. 🚧 ✅



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



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



```{r, eval = F}

usethis::use_mit_license()

```



### Bit D. Use life-cycle badge



```{r, eval = F}

usethis::use_lifecycle_badge("experimental") 

```



### 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}

knitrExtra::chunk_to_tests_testthat("test_calc_times_two_works")

```



```{r exit2, eval = T}

# for quick knit (exiting early) change eval to TRUE

# fs::dir_tree(recurse = T)

knitr::knit_exit()

```



### 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")

```



```{r exit3, eval = T}

# for quick knit (exiting early) change eval to TRUE

# fs::dir_tree(recurse = T)

knitr::knit_exit()

```



## 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)

```