title: "Get started with rcompendium"

output: rmarkdown::html_vignette

vignette: >

```{r, include = FALSE}

`rcompendium` makes easier the creation of R packages or research compendia

(i.e. a predefined files/folders structure) so that users can focus on the

code/analysis instead of wasting time organizing files. A full ready-to-work

structure is set up with some additional features: version control, remote

repository creation, CI/CD configuration (check package integrity under

several OS, test code with `testthat`, and build and deploy website using

`pkgdown`).

<br/>

Before using the package `rcompendium` you must follow these three steps.

<br/>

First ensure that **GIT** is correctly installed on your machine and linked to

RStudio. Read the Chapter 6 of

[Happy Git and GitHub for the useR](https://happygitwithr.com/install-git.html).

You also need to store your GIT credentials locally (i.e. for the project) or

globally (recommended). Run `gh::gh_whoami()` to see if your git and associated

credentials are correctly configured. You should see something like:

Otherwise you might need to run:

```{r eval = FALSE}

See `?gert::git_config_global_set` for further information.

<br/>

To create the GitHub repository directly from R, the package `rcompendium`

uses the function `usethis::use_github()`, a client to the GitHub REST API.

The interaction with this API required an authentication method: a

**GITHUB PAT** (Personal Access Token).

If you don't have a **GITHUB PAT** locally stored, you must:

1. visit the page [https://github.com/settings/tokens](https://github.com/settings/tokens)

and create a new token;

2. store it in the `~/.Renviron` file by using `usethis::edit_r_environ()`

and adding the following line: `GITHUB_PAT='ghp_99z9...z9'`.

Run `usethis::gh_token_help()` for more information about getting and

configuring a **GITHUB PAT**.

If everything is well configured, you should see something like this after

calling `gh::gh_whoami()`:

Then you will be able to create a GitHub repository directly from R!

<br />

You can use the arguments `given`, `family`, `email`, and `orcid`

directly with the functions `new_*()` and `add_*()`. But if you create

a lot a projects (packages and/or compendia) it can be frustrating in the

long run.

An alternative way is to use **ONCE AND FOR ALL** the function

`set_credentials()` to permanently store this information in the

`~/.Rprofile` file. If these arguments are set to `NULL` while calling any

function of the package, `rcompendium` will search their values in this file.

It will save your time (it's the purpose of this package).

Even if you have stored your credentials in the `~/.Rprofile` file you will

always be able to modify them on-the-fly (i.e. by using credentials arguments

in the functions `new_*()` and `add_*()`) or permanently by re-running

`set_credentials()`.

<br/>

The recommended workflow is:

1. Store your credentials with `set_credentials()` (if not already done);

2. **IMPORTANT -** Create an new empty RStudio project;

3. Run `new_package()` to create a new package structure or `new_compendium()`

to create a new research compendium structure;

4. Edit some metadata in `DESCRIPTION`, `CITATION`, and `README.Rmd`;

5. Start working (add data, write and document R functions, etc.);

6. And do not forget to commit your changes.

<br/>

In addition to these three setup functions (`set_credentials()`, `new_package()`,

`new_compendium()`), the package `rcompendium` offers 29 other functions.

These can be grouped as:

- `add_*()`: functions to add/update/overwrite files, configuration settings,

dependencies, badges, etc.;

- `get_*()`: functions to retrieve some information (available licenses, R

version, etc.).

Visit the [Reference page](https://frbcesab.github.io/rcompendium/reference/index.html)

for further details.

<br/>

**To sum up**

```{r eval = FALSE}

**N.B.** Users can also use functions from the package [`usethis`](https://usethis.r-lib.org/)

to add some missing features (e.g. `data/` and package release tools).

<br/>

- [Developing an R package](https://frbcesab.github.io/rcompendium/articles/developing_a_package.html)

- [Working with a compendium](https://frbcesab.github.io/rcompendium/articles/working_with_a_compendium.html)

<br/>

You are welcome to contribute to the `rcompendium` project. Please read our

[Contribution Guidelines](https://frbcesab.github.io/rcompendium/CONTRIBUTING.html).

Please note that the `rcompendium` project is released with a

[Contributor Code of Conduct](https://frbcesab.github.io/rcompendium/CODE_OF_CONDUCT.html).

By contributing to this project, you agree to abide by its terms.

<br/>

This package is the result of intense discussions and feedback from the training

course [Data Toolbox for Reproducible Research in Computational Ecology](https://rdatatoolbox.github.io/).

`rcompendium` is largely inspired by the package

[`rrtools`](https://github.com/benmarwick/rrtools) developed by

[Ben Marwick _et al._](https://github.com/benmarwick) and tries to respect the standard

defined by the community. **Special thanks to these developers!**