---
title: "Bookdown, quarto and other scripts dependencies"
author: "Sébastien Rochette"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{b-bookdown and other scripts dependencies}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<script type="text/javascript">
$(document).ready(function () {
  window.initializeCodeFolding("show" === "show");
});
</script>

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

## Load package {attachment}
```{r}
library(attachment)
```

## Use "dev/dev_history.R"

When building your package, create a file called "dev_history.R" in a "dev/" directory. You will store all "manual" calls to `devtools::xxx` and `usethis::xxx` in this script.  
Its first line should be :

```r
usethis::use_build_ignore("dev")
```

You can then call {attachment} in this file to help you build your description file.

## Use {attachment} with {bookdown} / {pagedown} / {quarto} dependencies

Dependencies of your Bookdown can be automatically installed if you use a "DESCRIPTION" file.  
Indeed, you can use this procedure to create the DESCRIPTION file for local installation or for Continuous Integration with GitLab Pages or GitHub Actions.
See for instance, the GitLab CI workflows in {gitlabr}: https://github.com/ThinkR-open/gitlabr/tree/main/inst/gitlab-ci

1. Create a "DESCRIPTION" file
```{r, eval=FALSE}
usethis::use_description()
```


2. Fill the "DESCRIPTION" file using `attachment::att_to_desc_from_is()`.
_Note that to include it directly in CI (as proposed in {gitlabr} templates), you may need to set `att_to_desc_from_is(must.exist = FALSE)`._   
_Note that `att_from_rmds()` also works for ".qmd" documents. You can use `att_from_qmds()` if you want, although for now there is no difference and it will also parse ".Rmd" documents._


```{r, eval=FALSE}
# bookdown Imports are in Rmds
imports <- c("bookdown", attachment::att_from_rmds("."))

attachment::att_to_desc_from_is(
  path.d = "DESCRIPTION",
  imports = imports, suggests = NULL, 
  must.exist = FALSE
)
```

3. Install dependencies from the DESCRIPTION file

```{r, eval=FALSE}
# install.packages("remotes")
remotes::install_deps()
```

4. Build your {bookdown} / {pagedown} / {quarto}

### Propose content for "Remotes" field

An interest of using DESCRIPTION to list your bookdown dependencies is to use packages from other sources than CRAN and list them in the 'Remotes' field.  
Here comes `set_remotes_to_desc()`, which adds packages that were installed from other source than CRAN to `Remotes:` field in DESCRIPTION.  

You can run it after `att_to_desc_from_is()`.

```{r eval=FALSE}
attachment::att_to_desc_from_is(
  path.d = "DESCRIPTION",
  imports = imports, suggests = NULL, 
  must.exist = FALSE
) %>%
  set_remotes_to_desc()
```


## Get all packages listed in "namespace"
You can get the list of packages in your package with `att_from_namespace()`

```{r, eval=FALSE}
att_from_namespace()
```

## Get all packages added using `pkg::function` or library/require
This reads all files in directories of R scripts (default to `R` directory of a package)

```{r, eval=FALSE}
att_from_rscripts()
```

Called in examples from R scripts: 

```{r, eval=FALSE}
att_from_examples()
```

## Get all packages called in your Rmd
If you have vignette, you may want to list extra libraries, not listed in your "Depends" list. This function applies to any Rmd file, of course.

```{r, eval=FALSE}
att_from_rmds()
```


## Get all packages called in your Rmd and show them in this same Rmd

Of course, you can also use {attachment} out of a package to list all package dependencies of R scripts using `att_from_rscripts()` or Rmd files using `att_from_rmds()`.  
If you want to run `att_from_rmds()` inside a Rmd as for this vignette, you will need to set `att_from_rmds(inside_rmd = TRUE)`

```{r, eval=TRUE}
dummypackage <- system.file("dummypackage", package = "attachment")

att_from_rmds(path = file.path(dummypackage, "vignettes"), inside_rmd = TRUE)
```