From 31d06098e91c3dd06bd16e66aed2fe0ab97a82d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 16 Dec 2019 17:24:42 +0100 Subject: [PATCH] Use Rmd fragments to limit duplications in README and vignette, fix #27 --- README.Rmd | 51 ++++++++++++++++++++ README.md | 99 +++++++++++++++++++++++++++++--------- man/rmdfragments/intro.Rmd | 5 ++ man/rmdfragments/use.Rmd | 17 +++++++ vignettes/namer.Rmd | 41 ++-------------- 5 files changed, 152 insertions(+), 61 deletions(-) create mode 100644 README.Rmd create mode 100644 man/rmdfragments/intro.Rmd create mode 100644 man/rmdfragments/use.Rmd diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 0000000..1bbbb97 --- /dev/null +++ b/README.Rmd @@ -0,0 +1,51 @@ +--- +output: github_document +--- + + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "man/figures/README-", + out.width = "100%" +) +``` + +# namer + + +[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![Travis build status](https://travis-ci.org/lockedata/namer.svg?branch=master)](https://travis-ci.org/lockedata/namer) [![Coverage status](https://coveralls.io/repos/github/lockedata/namer/badge.svg)](https://coveralls.io/r/lockedata/namer?branch=master) [![Locke Data Slack](https://img.shields.io/badge/Slack-discuss-blue.svg?logo=slack&longCache=true&style=flat)](https://join.slack.com/t/lockedata/shared_invite/enQtMjkwNjY3ODkwMzg2LTI1OGU1NTM3ZGIyZGFiNTdlODI3MzU2N2ZlNDczMjM4M2U2OWVmNDMzZTQ1ZGNlZDQ3MGM2MGVjMjI2MWIyMjI) + + +```{r child="man/rmdfragments/intro.Rmd"} +``` + +[![Example of use](man/figures/screenshot.png)](https://github.com/lockedata/pres-datascience/pull/1/files) + +## Use + +```{r child="man/rmdfragments/use.Rmd"} +``` + + +## Installation + +Install `namer` from CRAN + +```r +install.packages("namer") +``` + +Or get the dev version from this repo using: + +``` r +remotes::install_github("lockedata/namer") +``` + +## Contributing + +Wanna report a bug or suggest a feature? Great stuff! For more information on how to contribute check out [our contributing guide](.github/CONTRIBUTING.md). + + Please note that this R package is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this package project you agree to abide by its terms. diff --git a/README.md b/README.md index 924c91b..f0655fe 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,46 @@ -# namer - -[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![Travis build status](https://travis-ci.org/lockedata/namer.svg?branch=master)](https://travis-ci.org/lockedata/namer) [![Coverage status](https://coveralls.io/repos/github/lockedata/namer/badge.svg)](https://coveralls.io/r/lockedata/namer?branch=master) [![Locke Data Slack](https://img.shields.io/badge/Slack-discuss-blue.svg?logo=slack&longCache=true&style=flat)](https://join.slack.com/t/lockedata/shared_invite/enQtMjkwNjY3ODkwMzg2LTI1OGU1NTM3ZGIyZGFiNTdlODI3MzU2N2ZlNDczMjM4M2U2OWVmNDMzZTQ1ZGNlZDQ3MGM2MGVjMjI2MWIyMjI) - - -The goal of namer is to name the chunks of R Markdown files. It's your safety net when you've (willingly) forgotten to name most chunks of all R Markdown files in a folder. `namer` does *not* give meaningful labels to your chunks, but it gives them labels that won't change depending on their position like the automatic `knitr:::unnamed_chunk` function does when knitting. So you can e.g. shuffle your chunks and not loose their cache, or more easily debug over a whole folder! - -For context about _why_ you should name your R Markdown chunks, read [this blog post](https://masalmon.eu/2017/08/08/chunkpets/). - -The screenshot below is [a real life example](https://github.com/lockedata/pres-datascience/pull/1), result of running `namer::name_dir_chunks("pres")`. In each of the files in the dir "pres", it labelled chunks using the filename and numbers. -[![Example of use](man/figures/screenshot.png)](https://github.com/lockedata/pres-datascience/pull/1/files) + -## Installation - -Install the dev version from this repo using: +# namer -``` r -remotes::install_github("lockedata/namer") -``` + + +[![Project Status: WIP – Initial development is in progress, but there +has not yet been a stable, usable release suitable for the +public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) +[![Travis build +status](https://travis-ci.org/lockedata/namer.svg?branch=master)](https://travis-ci.org/lockedata/namer) +[![Coverage +status](https://coveralls.io/repos/github/lockedata/namer/badge.svg)](https://coveralls.io/r/lockedata/namer?branch=master) +[![Locke Data +Slack](https://img.shields.io/badge/Slack-discuss-blue.svg?logo=slack&longCache=true&style=flat)](https://join.slack.com/t/lockedata/shared_invite/enQtMjkwNjY3ODkwMzg2LTI1OGU1NTM3ZGIyZGFiNTdlODI3MzU2N2ZlNDczMjM4M2U2OWVmNDMzZTQ1ZGNlZDQ3MGM2MGVjMjI2MWIyMjI) + + +The goal of namer is to name the chunks of R Markdown files. It’s your +safety net when you’ve (willingly) forgotten to name most chunks of all +R Markdown files in a folder. `namer` does *not* give meaningful labels +to your chunks, but it gives them labels that won’t change depending on +their position like the automatic `knitr:::unnamed_chunk` function does +when knitting. So you can e.g. shuffle your chunks and not loose their +cache, or more easily debug over a whole folder\! + +For context about *why* you should name your R Markdown chunks, read +[this blog post](https://masalmon.eu/2017/08/08/chunkpets/). + +The screenshot below is [a real life +example](https://github.com/lockedata/pres-datascience/pull/1), result +of running `namer::name_dir_chunks("pres")`. In each of the files in the +dir “pres”, it labelled chunks using the filename and numbers. + +[![Example of +use](man/figures/screenshot.png)](https://github.com/lockedata/pres-datascience/pull/1/files) ## Use -This is a basic example which shows you how to solve a common problem. The "test" folder first contains R Markdown files with unnamed chunks. After running `name_dir_chunks`, they're all named, with names using the filenames as basis. +This is a basic example which shows you how to solve a common problem. +The “test” folder first contains R Markdown files with unnamed chunks. +After running `name_dir_chunks`, they’re all named, with names using the +filenames as basis. ``` r fs::dir_copy(system.file("examples", package = "namer"), @@ -30,16 +49,48 @@ name_dir_chunks("test") file.edit("test/example1.Rmd") ``` -There's also `name_chunks()` for use on a single R Markdown file; and `unname_chunks()` to unname all chunks of a single R Markdown file as well as `unname_dir_chunks()` to unnamme all chunks of all R Markdown files in a directory, which can be useful when cleaning your chunk labels. +There’s also `name_chunks()` for use on a single R Markdown file; and +`unname_chunks()` to unname all chunks of a single R Markdown file as +well as `unname_dir_chunks()` to unname all chunks of all R Markdown +files in a directory, which can be useful when cleaning your chunk +labels. -By default `unname_chunks()` unnames all chunks with exception of the 'setup' chunk. By using the argument `chunk_name_prefix` one can indicate the prefix of the labels that will be unnamed. Useful when one refers to a label by using chunk option `ref.label` so that it is inconvenient when that labeel is unnamed. By setting `chunk_name_prefix` equal to 'the filename with extension stripped' followed with a '-' (dash) only the labels generated by `name_chunks()` will be unnamed. +By default `unname_chunks()` unnames all chunks with exception of the +‘setup’ chunk. By using the argument `chunk_name_prefix` one can +indicate the prefix of the labels that will be unnamed. Useful when one +refers to a label by using chunk option `ref.label` so that it is +inconvenient when that labeel is unnamed. By setting `chunk_name_prefix` +equal to ‘the filename with extension stripped’ followed with a ‘-’ +(dash) only the labels generated by `name_chunks()` will be unnamed. -If you're working with RStudio, installing the package will have installed an addin for labelling chunks of *any R Markdown document you select*. +If you’re working with RStudio, installing the package will have +installed an addin for labelling chunks of *any R Markdown document you +select*. -**When using `namer`, please check the edits before pushing them to your code base. Such automatic chunk labelling is best paired with [version control](http://happygitwithr.com/).** +**When using `namer`, please check the edits before pushing them to your +code base. Such automatic chunk labelling is best paired with [version +control](http://happygitwithr.com/).** + +## Installation + +Install `namer` from CRAN + +``` r +install.packages("namer") +``` + +Or get the dev version from this repo using: + +``` r +remotes::install_github("lockedata/namer") +``` ## Contributing -Wanna report a bug or suggest a feature? Great stuff! For more information on how to contribute check out [our contributing guide](.github/CONTRIBUTING.md). +Wanna report a bug or suggest a feature? Great stuff\! For more +information on how to contribute check out [our contributing +guide](.github/CONTRIBUTING.md). - Please note that this R package is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this package project you agree to abide by its terms. +Please note that this R package is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By participating in this package project +you agree to abide by its terms. diff --git a/man/rmdfragments/intro.Rmd b/man/rmdfragments/intro.Rmd new file mode 100644 index 0000000..c0556c3 --- /dev/null +++ b/man/rmdfragments/intro.Rmd @@ -0,0 +1,5 @@ +The goal of namer is to name the chunks of R Markdown files. It's your safety net when you've (willingly) forgotten to name most chunks of all R Markdown files in a folder. `namer` does *not* give meaningful labels to your chunks, but it gives them labels that won't change depending on their position like the automatic `knitr:::unnamed_chunk` function does when knitting. So you can e.g. shuffle your chunks and not loose their cache, or more easily debug over a whole folder! + +For context about _why_ you should name your R Markdown chunks, read [this blog post](https://masalmon.eu/2017/08/08/chunkpets/). + +The screenshot below is [a real life example](https://github.com/lockedata/pres-datascience/pull/1), result of running `namer::name_dir_chunks("pres")`. In each of the files in the dir "pres", it labelled chunks using the filename and numbers. diff --git a/man/rmdfragments/use.Rmd b/man/rmdfragments/use.Rmd new file mode 100644 index 0000000..beaccae --- /dev/null +++ b/man/rmdfragments/use.Rmd @@ -0,0 +1,17 @@ +This is a basic example which shows you how to solve a common problem. The "test" folder first contains R Markdown files with unnamed chunks. After running `name_dir_chunks`, they're all named, with names using the filenames as basis. + +``` r +fs::dir_copy(system.file("examples", package = "namer"), + "test") +name_dir_chunks("test") +file.edit("test/example1.Rmd") +``` + +There's also `name_chunks()` for use on a single R Markdown file; and `unname_chunks()` to unname all chunks of a single R Markdown file as well as `unname_dir_chunks()` to unname all chunks of all R Markdown files in a directory, which can be useful when cleaning your chunk labels. + +By default `unname_chunks()` unnames all chunks with exception of the 'setup' chunk. By using the argument `chunk_name_prefix` one can indicate the prefix of the labels that will be unnamed. Useful when one refers to a label by using chunk option `ref.label` so that it is inconvenient when that labeel is unnamed. By setting `chunk_name_prefix` equal to 'the filename with extension stripped' followed with a '-' (dash) only the labels generated by `name_chunks()` will be unnamed. + +If you're working with RStudio, installing the package will have installed an addin for labelling chunks of *any R Markdown document you select*. + +**When using `namer`, please check the edits before pushing them to your code base. Such automatic chunk labelling is best paired with [version control](http://happygitwithr.com/).** + diff --git a/vignettes/namer.Rmd b/vignettes/namer.Rmd index 40aeb68..9673725 100644 --- a/vignettes/namer.Rmd +++ b/vignettes/namer.Rmd @@ -16,45 +16,12 @@ knitr::opts_chunk$set( ) ``` -The goal of namer is to name the chunks of R Markdown files. It's your safety net when you've (willingly) forgotten to name most chunks of all R Markdown files in a folder. `namer` does *not* give meaningful labels to your chunks, but it gives them labels that won't change depending on their position like the automatic `knitr:::unnamed_chunk` function does when knitting. So you can e.g. shuffle your chunks and not loose their cache, or more easily debug over a whole folder! - -For context about _why_ you should name your R Markdown chunks, read [this blog post](https://masalmon.eu/2017/08/08/chunkpets/). - -Check out [this real life example](https://github.com/lockedata/pres-datascience/pull/1), result of running `namer::name_dir_chunks("pres")`. - -## Use - -This is a basic example which shows you how to solve a common problem. The "test" folder first contains R Markdown files with unnamed chunks. After running `name_dir_chunks`, they're all named, with names using the filenames as basis. - -```r -temp_dir <- tempdir() -fs::dir_copy(system.file("examples", package = "namer"), - temp_dir) - # this is an example file that'd fail -fs::file_delete(file.path(temp_dir, "example4.Rmd")) -name_dir_chunks(temp_dir) -if(interactive()){ - file.edit(file.path(temp_dir, "example1.Rmd")) -} - -fs::dir_delete(temp_dir) +```{r child="../man/rmdfragments/intro.Rmd"} ``` -There's also `name_chunks` for use on a single R Markdown file; and `unname_chunks` to unname all chunks of a single R Markdown file which can be useful when cleaning your chunk labels. - -By default `unname_chunks` unnames all chunks with exception of the 'setup' chunk. By using the argument `chunk_name_prefix` one can indicate the prefix of the labels that will be unnamed. Useful when one refers to a label by using chunk option `ref.label` so that it is inconvenient when that label is unnamed. By setting `chunk_name_prefix` equal to 'the filename with extension stripped' followed with a '-' (dash) only the labels generated by `name_chunks` will be unnamed. In the following example the chunks labeled 'setup' and 'sessioninfo' will not be unnamed. - -```r -temp_file_path <- file.path(tempdir(check = TRUE), "example4.Rmd") +[![Example of use](../man/figures/screenshot.png)](https://github.com/lockedata/pres-datascience/pull/1/files) -file.copy(system.file("examples", "example4.Rmd", package = "namer"), - temp_file_path) -unname_chunks(temp_file_path,chunk_name_prefix='example4-') -if(interactive()){ - file.edit(temp_file_path) -} +## Use -file.remove(temp_file_path) +```{r child="../man/rmdfragments/use.Rmd"} ``` - -**When using `namer`, please check the edits before pushing them to your code base. Such automatic chunk labelling is best paired with [version control](http://happygitwithr.com/).**