---
title: "Build reports to document functions and unit tests"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Build reports to document functions and unit tests}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## `flow_doc()`

The `flow_doc()` function provides a way to draw all the functions of a package
and store them in an *html* report.

The `pkg` argument can be any package name, from base R, CRAN, or other 
including your local packages.

The `out` argument must be a path to an *html* or *md* file.

If `pkg` is provided but `out` is left `NULL`, the report will be printed to
a temporary file and will be opened automatically.

If you don't provide neither `pkg` nor `out`, a `diagrams.md` file will be created
at the root of your project folder, so that you can use `pkgdown::build_site`
to knit it into a new section after editing the YAML file properly.

The [Diagrams](https://moodymudskipper.github.io/flow/articles/Draw-a-function.html)
section of the [website](https://moodymudskipper.github.io/flow/)
was built this way, simply by using the following call :

```{r, eval = FALSE}
library(flow)
flow_doc(prefix = "##")
```

And the `_pkgdown.yml` file that is created by `usethis::use_pkgdown()` is edited
to contain :

```
navbar:
  structure:
    left:  [home, reference, articles, news, diagrams]
    right: [github]
  components:
    home: ~
    diagrams:
     text: Diagrams
     href: diagrams.html
```

## `flow_test()`

If you're using the package *{testthat}* for your unit tests, `flow_test()`
will help you explore them.

![flow_test](flow_test.gif)

Below I ran `flow::flow_test()` after opening the project of my package *{unglue}*.

It built a report with a tab for each test file,
then next to the code of each script we're able to visualize the diagram of
our package's functions and the logical path taken by the code, so we can easily see
what was tested and what potentially went wrong.

Successful tests are showed in green, while failed ones (none in the example above)
will be shown in red. To show only the failed tests, set the argument `failed_only`
to `TRUE`.

If its `out` parameter is left `NULL`, the report will be printed to
a temporary file and will be opened automatically.

Other parameters are forwarded to `flow_run()`.
