From d0bd74b7f690e63399afd4d6b6a88ea3b93e751b Mon Sep 17 00:00:00 2001 From: Jenny Bryan Date: Wed, 9 Nov 2022 16:39:56 -0800 Subject: [PATCH] Work on the (first) workflow section --- vignettes.Rmd | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/vignettes.Rmd b/vignettes.Rmd index 91f5ead4f..50d943445 100644 --- a/vignettes.Rmd +++ b/vignettes.Rmd @@ -47,27 +47,40 @@ To create your first vignette, run: usethis::use_vignette("my-vignette") ``` -This will: +This does the following: -1. Create a `vignettes/` directory. +1. Creates a `vignettes/` directory. -2. Add the necessary dependencies to `DESCRIPTION` (i.e. it adds knitr to the `Suggests` and `VignetteBuilder` fields). +2. Adds the necessary dependencies to `DESCRIPTION`, i.e. adds knitr to the `VignetteBuilder` field and adds both knitr and rmarkdown to `Suggests`. -3. Draft a vignette, `vignettes/my-vignette.Rmd`. +3. Drafts a vignette, `vignettes/my-vignette.Rmd`. -The draft vignette has been designed to remind you of the important parts of an R Markdown file. +4. Adds some patterns to `.gitignore` to ensure that files created as a side effect of previewing your vignettes are kept out of source control (we'll say more about this later). + +This draft document has been designed to remind you of the important parts of an R Markdown vignette. It serves as a useful reference when you're creating a new vignette. -Once you have this file, the workflow is straightforward: +You also call `use_vignette()` to create your second and all subsequent vignettes; it will just skip any setup that's already been done. + +Once you have the draft vignette, the workflow is straightforward: + +1. Start adding prose and code chunks to the vignette. + +2. Preview the rendered vignette. + + If you're documenting parts of your package that are under active development, it is important to build the vignette with the *current* source package. + You need to ensure that `library(yourpackage)` loads a bleeding edge version of your package. + Use `devtools::build_rmd()` in this case. + It builds your vignette against a (temporarily installed) development version of your package. -1. Modify the vignette. + If it's OK to build the vignette using the most-recently-installed version of your package, it's fine to use your usual workflow for rendering `.Rmd` files. + For example, press Ctrl/Cmd + Shift + K (or click ![](images/knit.png){width="45"}). -2. Press Ctrl/Cmd + Shift + K (or click ![](images/knit.png){width="45"}) to knit the vignette and preview the output. +3. Rinse and repeat until the vignette looks the way you want. -3. This builds with the installed package --- but you probably want the dev package. - Use `devtools::build_rmd()`. +If you're regularly checking your entire package (@sec-r-cmd-check), which we strongly recommend, this will also help to keep your vignettes in good working order. +In particular, this will alert you if a vignette makes use of a package that's not a formal dependency. -The check workflow, `Cmd + Shift + E`, will run the code in all vignettes. -This is a good way to verify that you've captured all the needed dependencies. +We're deliberately leaving one workflow issue to revisit below in SOME LATER SECTION. That's where we'll clarify the official mechanism for creating the rendered vignettes that appear in your package's bundled and installed form. ## Metadata {#vignette-metadata}