‘fusen’ v0.3: Better project templates, grouped functions and numerous other enhancements

You can read the original post in its original format on Rtask website by ThinkR here: ‘fusen’ v0.3: Better project templates, grouped functions and numerous other enhancements

{fusen} gets some maturity! v0.3 is a big rebranding for a more fluid experience, from beginners to advanced developers. Creating a fully documented and tested package has never been so easy and enjoyable. Experience “Rmd first” to the fullest.

At first, I imagined {fusen} to help beginners start building R packages. Following the ‘Rmd first’ method, I am convinced that building a package is accessible to anyone. With {fusen}, this is even more true.
However, I am surprised myself with the opportunity given by {fusen} to help me, I can say an advanced R user, to build properly documented and tested packages, with ease. This reduces my mental load for so many tasks during development. And my colleagues at ThinkR are even more convinced than me!
If you already are a R developer and plan to create a new package, or add a new functionnality to your existing package, try it out. You’ll tell me later if it allows you to build better documented and tested packages.

Install {fusen} from CRAN or r-universe

You can install the released CRAN version:

install.packages("fusen")

Full documentation for the CRAN version is here: https://thinkr-open.github.io/fusen/

You can install the development version of {fusen} from GitHub:

install.packages("fusen", 
                 repos = "https://thinkr-open.r-universe.dev")

Full documentation for the development version is here: https://thinkr-open.github.io/fusen/dev/

Meet the {fusen} project template

{fusen} is all about correctly separating and naming chunks.

• Create a new directory / new project with
  • RStudio template: File > New Project > New directory > Package using {fusen}
    
• Choose the template
  • Choose the template teaching the first time to see how {fusen} works,
  • Choose the template full the second time to answer most of your questions
    
• Open the “dev/flat_teaching.Rmd” to start setting up the package
• In this flat Rmd template, run the first chunks named description asking to describe your package and license it
  • The two lines of code look like these:

fill_description(fields = list(Title = "My Awesome Package"))
usethis::use_mit_license("Sébastien Rochette")

• Write your analysis and functionalities following the Rmd template
  • You probably develop them with a few examples and tests
  • For the first time, you can let the code as is, this is already the content for a working package
• Run the following code to transform the flat Rmd as an inflated package
  • This will open the vignette created and check the package

fusen::inflate(
  flat_file = "dev/flat_teaching.Rmd",
  vignette_name = "Get started",
  check = TRUE
)

That’s it! You built a package! A documented and tested package!

Create a {fusen} package from command line

• create_fusen() creates a project ready to inflate

library(fusen)
## Create a new project
dummypackage <- tempfile(pattern = "dummy")
# Create the template
dev_files <- create_fusen(dummypackage, template = "full", open = FALSE)
# Get the flat Rmd file template
flat_file <- dev_files[grepl("flat_", dev_files)]
# Fill description
fill_description(pkg = dummypackage, fields = list(Title = "Dummy Package"))
# Inflate the package
inflate(
  pkg = dummypackage, 
  flat_file = flat_file,
  vignette_name = "Get started", check = TRUE,
  open_vignette = FALSE)

Add new pre-filled flat templates for your function

add_flat_template() replaces add_dev_history() to add a new flat template in your “dev/” directory.

• Use add_flat_template("add") to add an new empty template with the set of three chunks function, example and test
• Use add_flat_template("add", flat_name = "my_func") to add a pre-filled template for your function named my_func()

There is also a RStudio Addin named “Add {fusen} chunks” that will add the set of three chunks, pre-filled with your function name, in the current Rmd file.

## my_func
```{r function-my_func}
#' Title
#' 
#' Description
#' 
#' @return
#' 
#' @export
my_func <- function(){
}
```
```{r example-my_func}
my_func()
```
```{r tests-my_func}
test_that("my_func works", {
  expect_true(inherits(my_func, "function")) 
})
```

Note that templates are now named flat_*.Rmd as we inflate a flat piece of paper into a nice package. The dev_history.Rmd file still exists to store all cross-functional tools like the {usethis} and {devtools} functions.

Group functions under the same R file after inflate

{fusen} inflates a flat Rmd template into multiple “.R” files in the “R/” and “tests/” directories. Although the development is only meant to take place in the flat template, you may want a concise organisation of these directories.

Version 0.3 allows to group some functions under the same “R/” and “tests/” files after inflate.

Functions are grouped in same R file and test file:

• if under same (level 1 + level 2) titles in the Rmd
• if they have the same @rdname roxygen tag
• if they have the same @filename roxygen tag (only recognized by ‘fusen’)
• if the function chunk get chunk option {r function-my_func, filename = "my_filename"}

Find out more in the new Tips & Tricks vignette

Tips and tricks

I gathered multiple tips and tricks in a new vignette:
https://thinkr-open.github.io/fusen/articles/tips-and-tricks.html

• Can I knit the content of the flat template ?
• How to declare packages with library() for the future vignette ?
• How to include examples that cannot be run ?
• Document your internal datasets in a function chunk as usual
• How to ignore some chunks ?
• How to get a pre-filled template for a specific function name ?
• How to Inflate multiple flat files ?
• How to store multiple functions in a unique R file ?

All other enhancements described in NEWS

Breaking changes

• add_flat_template() superseeds add_dev_history() with more advanced possibilities
• add_dev_history() is deprecated
• Vignette name to create is now set with inflate(vignette_name = "Get started") instead of name
• Flat name to inflate is now set with inflate(flat_file = "dev/flat_full.Rmd") instead of rmd

Major changes

• Grouping functions under the same file
• Check included now uses devtools::check() instead of rcmdcheck()
• Avoid creating vignette with inflate(vignette_name = NA)
• Decide whether or not to open vignette when inflate with inflate(open_vignette = FALSE)
• Improve documentation included in flat templates to reflect changes in using dev_history file
• Add Rstudio Addin to insert a new flat template
• Add Rstudio Addin to insert chunks for new function (@ColinFay)
• Deal with \dontrun{} in example chunks
• Allow short names for chunks: dev, fun, ex, test
• create_fusen() to create a {fusen} project from command line or with RStudio new project (@ALanguillaume)
• Add “do not edit by hand” in files generated

Minor changes

• add_flat_template() uses the flat_name to pre-fill the template with the first function name.
• Fix .onLoad functions file creation
• Allow R6Class() in function chunks
• Fix inflate function chunks with data or package documentation only
• Fix inflate with empty functions chunks
• Fix filename to inflate in templates with new calls of add_dev_history() (@Cervangirard)
• Default vignette name is now “Get started” creating “vignettes/get-started.Rmd”
• All open files are saved when using inflate() where {rstudioapi} works
• Ask to restart RStudio after first inflate

This post is better presented on its original ThinkR website here: ‘fusen’ v0.3: Better project templates, grouped functions and numerous other enhancements