---
title: "Get Started" 
author: "<h4>Authors: <i>`r auths <- eval(parse(text = gsub('person','c',read.dcf('../DESCRIPTION', fields = 'Authors@R'))));paste(auths[names(auths)=='given'],auths[names(auths)=='family'], collapse = ', ')`</i></h4>"
date: "<h4>Vignette updated: <i>`r format( Sys.Date(), '%b-%d-%Y')`</i></h4>"
output:
  rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{rworkflows} 
    %\usepackage[utf8]{inputenc}
    %\VignetteEngine{knitr::rmarkdown}
---


```{r, echo=FALSE, include=FALSE}
pkg <- read.dcf("../DESCRIPTION", fields = "Package")[1]
library(pkg, character.only = TRUE)
```

```R
library(`r pkg`)
```

# GitHub Secrets 

Before pushing changes to your new R package, you may want to set up one or more
[GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets):

* `GITHUB_TOKEN` [Optional]: Can grant access to private
    repos on GitHub Actions. You can generate your very own Personal
    Authentication Token using [these
    instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).   
* `DOCKER_TOKEN` [Optional]: Allows GitHub Actions to push to a
    [DockerHub](https://hub.docker.com) account. 

# `use_workflow`

## dynamic action

User only have to run `use_workflow` once per R package to create
a workflow file that calls the `rworkflows` action. 

```{r}
workflow <- rworkflows::use_workflow(run_bioccheck = FALSE, 
                                     run_rcmdcheck = TRUE,  
                                     run_pkgdown = TRUE, 
                                     run_docker = TRUE,
                                     docker_user = "bschilder",
                                     docker_org = "neurogenomicslab",
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())
```

## static workflow

Alternatively, you may use 

```{r}
workflow_static <- rworkflows::use_workflow(name = "rworkflows_static",
                                     run_bioccheck = FALSE, 
                                     run_rcmdcheck = TRUE,  
                                     run_pkgdown = TRUE, 
                                     run_docker = TRUE,
                                     docker_user = "bschilder",
                                     docker_org = "neurogenomicslab",
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())
```

# `use_badges`

This function creates a banner containing badges, 
a hex sticker (if one is available), and author names.

```{r, results='asis'}
badges <- rworkflows::use_badges()
```


# `use_dockerfile`

Create a *Dockerfile* that installs your R package and all its 
*Imports*/*Suggests*. It is normally not necessary for users to run this function themselves unless they would like to use it to create a template *Dockerfile* and then customise it further (rather than creating one on the fly).

```{r, results='asis'}
## Use default save_dir in practice
dockerfile <- rworkflows::use_dockerfile(save_dir = tempdir()) 
```

# Templates

You can generate templates for each of the following R package elements.
These templates are designed to dynamically autofill as as much information 
as possible (package name, date, authors) to minimise manual editing steps and
ensure documentation is as up-to-date as possible.

## README

README rmarkdown file. 
Allows you to run code inside to generate a README *markdown* file. 

```{r}
## Use default save_dir in practice
readme <- rworkflows::use_readme(save_dir = tempdir())
```

## Vignette: Get started

Generate a vignette on how to get started with your R package.
Requires additional editing to fill in examples.

```{r}
## Use default save_dir in practice
vignette1 <- rworkflows::use_vignette_getstarted(package = "mypackage",
                                                 save_dir = tempdir())
```


## Vignette: docker

Generate a vignette on how to install your R package via with your R package, 
RStudio, and all dependencies already installed.
This vignette does not require any manual editing after creation (unless you 
want to change things like port number, for example).

Note, this is only relevant when you have a container for your R package 
stored in a public Docker registry (e.g. GitHub Container Registry, DockerHub).
You can automatically generate one 
by using the `rworkflows` action with `run_docker=TRUE`:  
```R
rworkflows::use_workflow(run_docker = TRUE, 
                         docker_org = "neurogenomics")
```

If you're using the GitHub Container Registry, `docker_org` can simply be your
GH organization name or user name.
```{r}
## Use default save_dir in practice
vignette2 <- rworkflows::use_vignette_docker(docker_org = "neurogenomics",
                                             save_dir = tempdir())
```

# Adding Python

If your R package depends on python (e.g. via `reticulate`), 
the `rworkflows` action can also automatically install python for you.

## Using Python

You can instruct GitHub Actions to install a version of python, with whatever level of versioning specificiy you want (e.g. "3.10.11", "3.10", or even just "3").

If you supply one `python_version`, it will be applied to all runners. 
You also assign a different `python_version` to each `os`, as we do here:

```{r}
runners <- rworkflows::construct_runners(
  python_version = list("ubuntu-latest"="3.10.11",
                        "macOS-latest"="3.9",
                        "windows-latest"="3.9.1"))
workflow <- rworkflows::use_workflow(runners = runners,
                                     preview = TRUE,
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())
```


## Using conda

Optionally, you can tell it to create and activate a conda environment to use.
`rworkflows::construct_conda_yml` is a helper function to create conda yaml 
files for you.

Here we construct our yaml file that specifies what we want in our conda env.
Make sure you write the yaml to your project directory, 
so that it gets pushed to GitHub (and thus can be found after 
checking out your repo on  GitHub Actions).

See [here](https://github.com/RajLabMSSM/echoconda/tree/main/inst/conda) 
for some examples of 
```{r}
environment_file <- construct_conda_yml(name = "myenv", 
                                        channels = c("conda-forge",
                                                     "bioconda"),
                                        dependencies = c("python>=3.7",
                                                         "scanpy",
                                                         "anndata"), 
                                        pip = c("scarches",
                                                "magic-impute"),
                                        preview = TRUE)
```

You could also simply provide a URL to a publicly accessible 
conda yaml file stored elsewhere.
```r
environment_file <- "https://github.com/RajLabMSSM/echoconda/raw/main/inst/conda/scanpy.yml"
```

Now we can supply the conda `environment_file` path, and Miniconda will 
automatically be installed to build the conda env on all of 
your GitHub Actions runners. 
```{r} 
workflow <- rworkflows::use_workflow(environment_file = environment_file, 
                                     preview = TRUE, 
                                     force_new = TRUE,
                                     ## Use default save_dir in practice
                                     save_dir = tempdir())
```
 


```{r}
## Cleanup files
try({file.remove(environment_file)})
```


# Session Info 

<details> 

```{r Session Info}
utils::sessionInfo()
```

</details>  

<hr>