fusen package template

examples/my.fusen.pkg/.Rbuildignore

+
+^dev$
+^\.here$

examples/my.fusen.pkg/dev/.gitignore

+
+*.html
+*.R

examples/my.fusen.pkg/dev/0-dev_history.Rmd

+---
+title: "Development actions history"
+output: html_document
+editor_options: 
+  chunk_output_type: console
+---
+
+All commands that you use to use when developing packages...
+
+# First time just after creating the project
+
+- Fill the following chunk to create the DESCRIPTION of your package
+
+```{r description, eval=FALSE}
+# Describe your package
+fusen::fill_description(
+  pkg = here::here(),
+  fields = list(
+    Title = "Build A Package From Rmarkdown File",
+    Description = "Use Rmarkdown First method to build your package. Start your package with documentation. Everything can be set from a Rmarkdown file in your project.",
+    `Authors@R` = c(
+      person("Sebastien", "Rochette", email = "sebastien@thinkr.fr", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1565-9313")),
+      person(given = "ThinkR", role = "cph")
+    )
+  )
+)
+# Define License with use_*_license()
+usethis::use_mit_license("Sébastien Rochette")
+```
+
+# Start using git
+
+```{r, eval=FALSE}
+usethis::use_git()
+# Deal with classical files to ignore
+usethis::git_vaccinate()
+# Use main for primary branch
+usethis::git_default_branch_rename()
+```
+
+# Set extra sources of documentation
+
+```{r, eval=FALSE}
+# Install a first time
+remotes::install_local()
+# README
+usethis::use_readme_rmd()
+# Code of Conduct
+usethis::use_code_of_conduct("contact@fake.com")
+# NEWS
+usethis::use_news_md()
+```
+
+**From now, you will need to "inflate" your package at least once to be able to use the following commands. Let's go to your flat template, and come back here later if/when needed.**
+
+
+# Package development tools
+## Use once
+
+```{r, eval=FALSE}
+# Pipe
+usethis::use_pipe()
+
+# package-level documentation
+usethis::use_package_doc()
+
+# GitHub
+# Add your credentials for GitHub
+gitcreds::gitcreds_set()
+# Send your project to a new GitHub project
+usethis::use_github()
+
+# Set Continuous Integration
+# _GitHub
+usethis::use_github_action_check_standard()
+usethis::use_github_action("pkgdown")
+usethis::use_github_action("test-coverage")
+# _GitLab
+gitlabr::use_gitlab_ci(type = "check-coverage-pkgdown")
+
+# Add new flat template
+fusen::add_flat_template("add")
+```
+
+## Use everytime needed
+
+```{r}
+# Simulate package installation
+pkgload::load_all()
+
+# Generate documentation and deal with dependencies
+attachment::att_amend_desc()
+
+# Check the package
+devtools::check()
+```
+
+# Share the package
+
+```{r}
+# set and try pkgdown documentation website
+usethis::use_pkgdown()
+pkgdown::build_site()
+
+# build the tar.gz with vignettes to share with others
+devtools::build(vignettes = TRUE)
+```
+

examples/my.fusen.pkg/dev/dev_history.Rmd

+---
+title: "Development actions history"
+output: html_document
+editor_options: 
+  chunk_output_type: console
+---
+
+# Initial setup (to be run once)
+
+## Development framework
+
+### git
+
+```{r dev-init-git, eval=FALSE}
+# use git
+usethis::use_git()
+# deal with classical files to ignore
+usethis::git_vaccinate()
+# ignore .git sub-directory when building
+usethis::use_build_ignore(".git")
+# testthat snapshot
+usethis::use_git_ignore("test/testthat/_snaps/")
+```
+
+### CI setup
+```{r dev-init-ci, eval=FALSE}
+gitlabr::use_gitlab_ci(
+    image = "rocker/verse:latest",
+    type = "check-coverage-pkgdown"
+)
+```
+
+## Extra documentation
+
+```{r dev-init-extra-doc, eval=FALSE}
+# README
+usethis::use_readme_rmd()
+```
+
+```{r dev-init-website}
+# set pkgdown documentation website
+usethis::use_pkgdown()
+```
+
+## Misc
+
+```{r dev-init-misc, eval=FALSE}
+# additional files/folders to ignore during build
+usethis::use_build_ignore("draft")
+# testthat snapshot
+usethis::use_build_ignore("test/testthat/_snaps/")
+```
+
+# Package development tools
+
+## Package description and meta-data
+
+```{r description, eval=FALSE}
+# DESCRIPTION
+fusen::fill_description(
+    pkg = here::here(),
+    fields = list(
+        Title = "Build A Package From Rmarkdown File",
+        Description = "Use Rmarkdown First method to build your package. Start your package with documentation. Everything can be set from a Rmarkdown file in your project.",
+        `Authors@R` = c(
+            person("Sebastien", "Rochette", email = "sebastien@thinkr.fr", role = c("aut", "cre"), comment = c(ORCID = "0000-0002-1565-9313")),
+            person(given = "ThinkR", role = "cph")
+        )
+    ),
+    overwrite = TRUE
+)
+# License
+usethis::use_agpl_license()
+# Roxygen markdown
+usethis::use_roxygen_md()
+# use magrittr's pipe operator %>%
+usethis::use_pipe()
+# package-level documentation
+usethis::use_package_doc()
+```
+
+## Inflate package and document
+
+```{r development-pipeline}
+# Generate the package main functions and vignette
+fusen::inflate(
+    flat_file = "dev/flat_package.Rmd", 
+    vignette_name = "Getting started with my package", 
+    open_vignette = FALSE,
+    check = FALSE,
+    overwrite = 'yes'
+)
+
+# Simulate package installation
+pkgload::load_all()
+
+# Generate documentation and deal with dependencies
+attachment::att_amend_desc()
+```
+
+## Test and check
+
+```{r development-check}
+# Run the test
+devtools::test()
+
+# Check the package
+devtools::check()
+```
+
+## Share the package
+
+```{r development-website}
+# run pkgdown documentation website
+pkgdown::build_site()
+```
+
+## Build source package
+
+```{r development-build}
+# build the tar.gz with vignettes to share with others
+devtools::build(vignettes = TRUE)
+```
+

examples/my.fusen.pkg/dev/flat_full.Rmd

+---
+title: "flat_full.Rmd for working package"
+output: html_document
+editor_options: 
+  chunk_output_type: console
+---
+
+<!-- Run this 'development' chunk -->
+<!-- Store every call to library() that you need to explore your functions -->
+
+```{r development, include=FALSE}
+library(testthat)
+```
+
+<!--
+ You need to run the 'description' chunk in the '0-dev_history.Rmd' file before continuing your code there.
+
+If it is the first time you use {fusen}, after 'description', you can directly run the last chunk of the present file with inflate() inside.
+--> 
+
+```{r development-load}
+# Load already included functions if relevant
+pkgload::load_all(export_all = FALSE)
+```
+
+# Include some data examples in your package
+
+<!-- 
+ Store your dataset in a directory named "inst/" at the root of your project.
+ Use it for your tests in this Rmd thanks to `pkgload::load_all()` to make it available
+and `system.file()` to read it in your examples.
+
+- There already is a dataset in the "inst/" directory to be used in the examples below
+-->
+
+```{r development-dataset}
+# Run all this chunk in the console directly
+# There already is a dataset in the "inst/" directory
+# Make the dataset file available to the current Rmd during development
+pkgload::load_all(path = here::here(), export_all = FALSE)
+
+# You will be able to read your example data file in each of your function examples and tests as follows - see chunks below
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+
+nyc_squirrels
+```
+
+
+# The first function of the package: Calculate the median of a vector
+
+<!--
+Create a chunk for the core of the function
+
+- The chunk needs to be named `function` at least
+- It contains the code of a documented function
+- The chunk can also be named `function-my_median` to make it easily
+findable in your Rmd
+- Let the `@examples` part empty, and use the next `examples` chunk instead to present reproducible examples
+
+After inflating the template
+
+-  This function code will automatically be added in a new file in the "R/" directory
+-->
+
+```{r function}
+#' My median
+#'
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+#'
+#' @return
+#' Median of vector x
+#' @export
+#'
+#' @examples
+my_median <- function(x, na.rm = TRUE) {
+  if (!is.numeric(x)) {stop("x should be numeric")}
+  stats::median(x, na.rm = na.rm)
+}
+```
+
+<!--
+Create a chunk with an example of use for your function
+
+- The chunk needs to be named `examples` at least
+- It contains working examples of your function
+- The chunk is better be named `examples-my_median` to be handled
+correctly when inflated as a vignette
+
+After inflating the template
+
+-  This example will automatically be added in the '@examples' part of our function above in the "R/" directory
+- This example will automatically be added in the vignette created from this Rmd template
+-->
+
+```{r examples}
+my_median(1:12)
+
+# Example with your dataset in "inst/"
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+# Apply my function
+my_median(nyc_squirrels[,"hectare_squirrel_number"])
+```
+
+<!--
+Create a chunk with a test of use for your function
+
+- The chunk needs to be named `tests` at least
+- It contains working tests of your function
+- The chunk is better be named `tests-my_median` to be handled
+correctly when inflated as a vignette
+
+After inflating the template
+
+-  This test code will automatically be added in the "tests/testthat/" directory
+-->
+
+```{r tests}
+test_that("my_median works properly and show error if needed", {
+  expect_true(my_median(1:12) == 6.5)
+  expect_error(my_median("text"))
+})
+
+# Test with your dataset in "inst/"
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+# Apply test on my function
+test_that("my_median works properly with internal dataset", {
+  expect_equal(my_median(nyc_squirrels[,"hectare_squirrel_number"]), 3)
+})
+```
+
+# Calculate the mean of a vector
+
+<!--
+There can be other functions, examples and tests in your flat template.
+Each of them will be inflated in a different file, provided that there is a level-1 or level-2 section title to separate from previous functions.
+-->
+
+## Use sub-functions in the same chunk
+
+```{r function-my_other_median}
+#' My Other median
+#'
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+#'
+#' @return
+#' Median of vector x
+#' @export
+#'
+#' @examples
+my_other_median <- function(x, na.rm = TRUE) {
+  if (!is.numeric(x)) {stop("x should be numeric")}
+  sub_median(x, na.rm =na.rm)
+}
+
+#' Core of the median not exported
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+sub_median <- function(x, na.rm = TRUE) {
+  stats::median(x, na.rm)
+}
+```
+
+```{r examples-my_other_median}
+my_other_median(1:12)
+```
+
+```{r tests-my_other_median}
+test_that("my_median works properly and show error if needed", {
+  expect_true(my_other_median(1:12) == 6.5)
+  expect_error(my_other_median("text"))
+})
+```
+
+<!--
+# There can be development actions
+
+Create a chunk with 'development' actions
+
+- The chunk needs to be named `development` or `dev`
+- It contains functions that are used for package development only
+- Note that you may want to store most of these functions in the 0-dev_history.Rmd file
+
+These are only included in the present flat template file, their content will not be part of the package anywhere else.
+-->
+
+```{r development-inflate, eval=FALSE}
+# Keep eval=FALSE to avoid infinite loop in case you hit the knit button
+# Execute in the console directly
+fusen::inflate(flat_file = "dev/flat_full.Rmd", vignette_name = "Get started")
+```
+
+
+# Inflate your package
+
+You're one inflate from paper to box.
+Build your package from this very Rmd using `fusen::inflate()`
+
+- Verify your `"DESCRIPTION"` file has been updated
+- Verify your function is in `"R/"` directory
+- Verify your test is in `"tests/testthat/"` directory
+- Verify this Rmd appears in `"vignettes/"` directory

examples/my.fusen.pkg/dev/flat_package.Rmd

+---
+title: "flat_package.Rmd for working package"
+output: html_document
+editor_options: 
+  chunk_output_type: console
+---
+
+<!-- Run this 'development' chunk -->
+<!-- Store every call to library() that you need to explore your functions -->
+
+```{r development, include=FALSE}
+library(testthat)
+```
+
+<!--
+ You need to run the 'description' chunk in the '0-dev_history.Rmd' file before continuing your code there.
+
+If it is the first time you use {fusen}, after 'description', you can directly run the last chunk of the present file with inflate() inside.
+--> 
+
+```{r development-load}
+# Load already included functions if relevant
+pkgload::load_all(export_all = FALSE)
+```
+
+# Include some data examples in your package
+
+<!-- 
+ Store your dataset in a directory named "inst/" at the root of your project.
+ Use it for your tests in this Rmd thanks to `pkgload::load_all()` to make it available
+and `system.file()` to read it in your examples.
+
+- There already is a dataset in the "inst/" directory to be used in the examples below
+-->
+
+```{r development-dataset}
+# Run all this chunk in the console directly
+# There already is a dataset in the "inst/" directory
+# Make the dataset file available to the current Rmd during development
+pkgload::load_all(path = here::here(), export_all = FALSE)
+
+# You will be able to read your example data file in each of your function examples and tests as follows - see chunks below
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+
+nyc_squirrels
+```
+
+
+# The first function of the package: Calculate the median of a vector
+
+<!--
+Create a chunk for the core of the function
+
+- The chunk needs to be named `function` at least
+- It contains the code of a documented function
+- The chunk can also be named `function-my_median` to make it easily
+findable in your Rmd
+- Let the `@examples` part empty, and use the next `examples` chunk instead to present reproducible examples
+
+After inflating the template
+
+-  This function code will automatically be added in a new file in the "R/" directory
+-->
+
+```{r function}
+#' My median
+#'
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+#'
+#' @return
+#' Median of vector x
+#' @export
+#'
+#' @examples
+my_median <- function(x, na.rm = TRUE) {
+  if (!is.numeric(x)) {stop("x should be numeric")}
+  stats::median(x, na.rm = na.rm)
+}
+```
+
+<!--
+Create a chunk with an example of use for your function
+
+- The chunk needs to be named `examples` at least
+- It contains working examples of your function
+- The chunk is better be named `examples-my_median` to be handled
+correctly when inflated as a vignette
+
+After inflating the template
+
+-  This example will automatically be added in the '@examples' part of our function above in the "R/" directory
+- This example will automatically be added in the vignette created from this Rmd template
+-->
+
+```{r examples}
+my_median(1:12)
+
+# Example with your dataset in "inst/"
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+# Apply my function
+my_median(nyc_squirrels[,"hectare_squirrel_number"])
+```
+
+<!--
+Create a chunk with a test of use for your function
+
+- The chunk needs to be named `tests` at least
+- It contains working tests of your function
+- The chunk is better be named `tests-my_median` to be handled
+correctly when inflated as a vignette
+
+After inflating the template
+
+-  This test code will automatically be added in the "tests/testthat/" directory
+-->
+
+```{r tests}
+test_that("my_median works properly and show error if needed", {
+  expect_true(my_median(1:12) == 6.5)
+  expect_error(my_median("text"))
+})
+
+# Test with your dataset in "inst/"
+datafile <- system.file("nyc_squirrels_sample.csv", package = "my.fusen.pkg")
+nyc_squirrels <- read.csv(datafile, encoding = "UTF-8")
+# Apply test on my function
+test_that("my_median works properly with internal dataset", {
+  expect_equal(my_median(nyc_squirrels[,"hectare_squirrel_number"]), 3)
+})
+```
+
+# Calculate the mean of a vector
+
+<!--
+There can be other functions, examples and tests in your flat template.
+Each of them will be inflated in a different file, provided that there is a level-1 or level-2 section title to separate from previous functions.
+-->
+
+## Use sub-functions in the same chunk
+
+```{r function-my_other_median}
+#' My Other median
+#'
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+#'
+#' @return
+#' Median of vector x
+#' @export
+#'
+#' @examples
+my_other_median <- function(x, na.rm = TRUE) {
+  if (!is.numeric(x)) {stop("x should be numeric")}
+  sub_median(x, na.rm =na.rm)
+}
+
+#' Core of the median not exported
+#' @param x Vector of Numeric values
+#' @inheritParams stats::median
+sub_median <- function(x, na.rm = TRUE) {
+  stats::median(x, na.rm)
+}
+```
+
+```{r examples-my_other_median}
+my_other_median(1:12)
+```
+
+```{r tests-my_other_median}
+test_that("my_median works properly and show error if needed", {
+  expect_true(my_other_median(1:12) == 6.5)
+  expect_error(my_other_median("text"))
+})
+```
+
+<!--
+# There can be development actions
+
+Create a chunk with 'development' actions
+
+- The chunk needs to be named `development` or `dev`
+- It contains functions that are used for package development only
+- Note that you may want to store most of these functions in the 0-dev_history.Rmd file
+
+These are only included in the present flat template file, their content will not be part of the package anywhere else.
+-->
+
+```{r development-inflate, eval=FALSE}
+# Keep eval=FALSE to avoid infinite loop in case you hit the knit button
+# Execute in the console directly
+fusen::inflate(flat_file = "dev/flat_package.Rmd", vignette_name = "Get started")
+```
+
+
+# Inflate your package
+
+You're one inflate from paper to box.
+Build your package from this very Rmd using `fusen::inflate()`
+
+- Verify your `"DESCRIPTION"` file has been updated
+- Verify your function is in `"R/"` directory
+- Verify your test is in `"tests/testthat/"` directory
+- Verify this Rmd appears in `"vignettes/"` directory