---
title: "mortar"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{mortar}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The goal of `mortar` is to standardize how we USGS Data Science Community of Practice (DS CoP) structure our collaborative projects.
The package's functionality focuses on setting up project directories using the DS CoP conventions.
Think of `mortar` as a collection of helper functions for creating files and folders we often use in our workflows.

```{r setup}
library(mortar)
```

## Set up a USGS git repo with `use_project_usgs()`

You may want or need to include common files in a project's git repo to adhere to coding conventions or standards.
These include a **README** that summarizes basic information about a repo, a **License** that details how the contents of a repo can be used, and others.

The `use_*_usgs()` family of functions create these sorts of files based on USGS-specific templates.
These functions are heavily inspired by similar functions from the [`usethis`](https://usethis.r-lib.org/) R package.

At the top of each of these template files, the following message is included:

> -**NOTE: this is a template created using the `mortar` package. The contents below are for illustrative purposes and should be edited to reflect your use case. This message can be deleted in acknowledgement that you've added this file to your project.**

This acts as a nudge to the author to update the documentation to the specifics of the project. It also acts as a quality control measure, allowing code authors and reviewers to ensure that they have at least opened and looked at each of these files.

For example, you can add a .gitignore file to your repo with some pre-set (often forgotten) ignores using the following.
If you don't like the contents of these template files, you're able to customize it using or `additions` argument or to edit them afterward to your needs.

```{r eval=FALSE}
use_gitignore_usgs(additions = c("scratch*", "*/tmp/*"))
```

This creates the standard .gitignore with additional lines for `scratch*` and `*/tmp/*`.
Run ``?mortar::`use-file-usgs` `` to view the function family's documentation and more examples.

`use_project_usgs()` generates all the common files for your repository in one function call: CHANGELOG.md, code.json, CODE_OF_CONDUCT.md, CONTRIBUTING.md, DISCLAMER.md, .gitignore, LICENSE.md, and README.md.

```{r eval=FALSE}
use_project_usgs(
  gitignore_additions = c("scratch*", "*/tmp/*"),
  readme_rmd = TRUE,
  disclaimer_approved = FALSE
)
```

Run `?mortar::use_project_usgs` to view the function's documentation and more examples.

## Set up a `targets` project with `tar_init()`

The `tar_init()` function will initialize a `targets` pipeline project directory according to the DS CoP conventions. Internal USGS users can see more on this in section 12 of the Targets 2 training course.
Run this function at the beginning of a `targets` pipeline project to avoid manually setting up the project directory (and forgetting to add those pesky `.empty` files in each sub-directory).

The call below illustrates how to use `tar_init()`.

```{r eval=FALSE}
tar_init(
  phase_names = c("fetch","process","summarize"),
  phase_subdirs = c("src","out"),
  use_leading_zeros = TRUE
)
```

Under the hood, `tar_init()` basically just repeatedly calls `dir.create()` and `file.create()` to accomplish the following tasks:

1. Creates a `_targets.R` file in the project's root directory with some general starter code.
2. Creates `.R` scripts and directories in the projects root directory for each phase of the pipeline like `01_fetch.R` and `01_fetch/`, etc.
3. For each phase directory, creates sub-directories therein, such as `src` and `out`.
4. Adds a `.empty` file within each sub-directory so that it will be tracked by git.

Run `?mortar::tar_init` to view the function's documentation and more examples.