# How to use fusen

    library(fusen)

# All steps to create a package with {fusen} from one Rmd file

- Create a new directory / new project with
  - RStudio template: File > New Project > New directory > Package using {fusen}
  - Choose the template `teaching` to start
  - Or command line: `create_fusen("path/to/new/project", template = "teaching")`
- Open the “dev/flat_teaching” Rmd to start setting up the package
- Run the content of the first `development` chunk with `library(testthat)` inside
- Modify and run the content of the chunk named `description` asking to describe your package and license it
  - For the first time, you can let the code as is, this is already the content for a working package
- Follow the `"dev/flat_teaching.Rmd"` template to write your documentation and build your functions and test your examples.
  - Chunk named `function` gets the code of a function
  - Chunk named `example` gets the code for examples of using the function. This will be used for function `@examples` and will be kept for the vignette
  - Chunk named `tests` gets the code for unit testing
  - Chunk named `development` gets the code for development purposes, usually only used once like {usethis} functions
- Run the `dev-inflate` chunk to inflate the flat template and transform it as an inflated package with functions, unit tests and the current Rmd template transformed as a vignette. And check.
- Build your {pkgdown} site to verify everything is at the right place

> Create multiple `"flat_xxx.Rmd"` files with `fusen::add_flat_template(template = "add")` if needed

## Fill your package Description

Function `fill_description()` requires the description of your package: What does it do? Who are the developers?
This will fill the DESCRIPTION file in the proper way.

    fill_description(
      pkg = dummypackage,
      fields = list(
        Title = "Build A Package From Rmarkdown file",
        Description = paste(
          "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("John", "Doe", email = "john@email.me", role = c("aut", "cre"), comment = c(ORCID = "0000-0000-0000-0000")),
          person(given = "Company", role = "cph")
        )
      )
    )

## Inflate your package from the flat Rmd template

You’re one inflate from flat paper to box. Build your package from the flat Rmd template using the `inflate()` command below.

After that, you can:

- 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
- Build your documentation using `usethis::use_pkgdown()` then `pkgdown::build()` for vignette and examples checks

    fusen::inflate(
      flat_file = "dev/flat_teaching.Rmd",
      vignette_name = "Exploration of my Data",
      open_vignette = TRUE,
      document = TRUE,
      check = TRUE
    )

# Create a new package from command line directly, using a pre-defined template

- Build a package from Rmd template in a temporary directory
  - This is for testing purposes

    # Create a new project
    dummypackage <- tempfile(pattern = "dummy")

    # {fusen} steps
    dev_file <- create_fusen(dummypackage, template = "teaching", open = FALSE)
    # Description
    fusen::fill_description(pkg = dummypackage, fields = list(Title = "Dummy Package"))

    # From inside the package
    usethis::with_project(dummypackage, {
      # Define License with use_*_license()
      usethis::use_mit_license("John Doe")

      # You may need to execute inflate() in the console directly
      fusen::inflate(
        pkg = dummypackage,
        flat_file = dev_file,
        vignette_name = "Get started"
      )
    })

    # Explore directory of the package
    browseURL(dummypackage)

    # Delete dummy package
    unlink(dummypackage, recursive = TRUE)

# Add a new “flat_template.Rmd” template in “dev/” directory

    # Add an additional dev template
    add_flat_template(template = "add", pkg = dummypackage)
    # or directly
    add_additional(pkg = dummypackage)

# There can be development actions

These are only included in the flat template file, their content will not be part of the package anywhere else.

Name the following chunk with `{r development-something, eval=FALSE}`

    ```{r development-inflate, eval=FALSE}
    # Run but keep eval=FALSE to avoid infinite loop

    usethis::use_mit_license("John Doe")

    # Execute in the console directly

    fusen::inflate(flat_file = "dev/dev_history.Rmd")
    ```

# Limitations

- One title / one chunk is for one function
- `examples` and `tests` chunks need to be placed after the associated `function` chunk
- You can add sub-functions in the `function` chunk to store them in the same R file, but they won’t have `@examples`. Only the first function of the chunk will be able to get examples.
- As for any Rmarkdown file, chunk names need to be unique. Thus, you better use `examples-myfunction`, `examples-myotherfunction`, …
- Do not forget to regularly clear your Workspace to avoid functions hidden by global environment