README

- WIP updated readme
ElianHugh · Oct 18, 2023 · 8a4e103 · 8a4e103
1 parent 7738389
commit 8a4e103
Show file tree

Hide file tree

Showing 5 changed files with 114 additions and 46 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -4,7 +4,7 @@ Version: 0.0.0.9000
 Authors@R:
     person("Elian", "Thiele-Evans", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-8008-3165"))
-Description: Generate quarto-compliant markdown elements programatically.
+Description: Programatically generate quarto-compliant markdown elements.
 License: GPL (>= 3)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
@@ -14,3 +14,5 @@ Imports:
 Suggests:
     testthat (>= 3.0.0)
 Config/testthat/edition: 3
+URL: https://github.com/ElianHugh/quartools
+BugReports: https://github.com/ElianHugh/quartools/issues
diff --git a/README.Rmd b/README.Rmd
@@ -4,25 +4,29 @@ output: github_document
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-```{r, include = FALSE}
-knitr::opts_chunk$set(
-  collapse = TRUE,
-  comment = "#>",
-  fig.path = "man/figures/README-",
-  out.width = "100%"
-)
-```
-
 # quartools
 
 <!-- badges: start -->
+[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
 <!-- badges: end -->
 
-The goal of quartools is to ...
+_quartools_ allows for the creation of quarto-compliant markdown via R function calls. As _quartools_ generates quarto-compliant markdown, and _not_ HTML tags, the content will work on any quarto output format.
+
+
+## Why quartools?
+
+At work, I ran into an issue where I was generating hundreds of parameterised reports that would be similar with subtle differences in content. I found myself leaning on R for programmatic markup creation, which meant that I could have one master document that I worked on. My prototype version (in other words, functions I threw together for work) required a lot of constant chunk configuration, and wasn't particularly user-friendly nor elegant. _quartools_ is a more streamlined version of my prototype, with the added benefit of it requiring little to no setup on the end user's part.
+
 
 ## Installation
 
-You can install the development version of quartools from [GitHub](https://github.com/) with:
+### Release build
+
+``` r
+install.packages('quartools', repos = 'https://elianhugh.r-universe.dev')
+```
+
+### Development build
 
 ``` r
 # install.packages("devtools")
@@ -31,25 +35,26 @@ devtools::install_github("ElianHugh/quartools")
 
 ## Example
 
-This is a basic example which shows you how to solve a common problem:
+### My First Div
+
+The simplest way to create a div block element with quartools is via the `div` function. Note that the chunk configuration of `results: asis` is not necessary.
 
 ```{r example}
 library(quartools)
-## basic example code
+div("Hello world!")
 ```
 
-What is special about using `README.Rmd` instead of just `README.md`? You can include R chunks like so:
+It is also possible to supply attributes to the div block element via the `attr` parameter (the callout will not work on GitHub):
 
-```{r cars}
-summary(cars)
+```{r}
+div("I'm a tip!", attr = ".callout-tip")
 ```
 
-You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. `devtools::build_readme()` is handy for this.
-
-You can also embed plots, for example:
+### Apply
 
-```{r pressure, echo = FALSE}
-plot(pressure)
-```
+We can leverage the `apply` family of functions ability to loop over list elements to simplify creating many divs at once. Normally this would require a workaround to allow for printing directly as markdown content, but _quartools_ exports the `mdapply` function (read: "markdown apply") which allows for directly printing the result as valid markdown content.
 
-In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN.
+```{r}
+my_favourite_letters <- letters[1L:3L]
+mdapply(my_favourite_letters, div)
+```
diff --git a/README.md b/README.md
@@ -4,14 +4,36 @@
 # quartools
 
 <!-- badges: start -->
+
+[![Lifecycle:
+experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
 <!-- badges: end -->
 
-The goal of quartools is to …
+*quartools* allows for the creation of quarto-compliant markdown via R
+function calls. As *quartools* generates quarto-compliant markdown, and
+*not* HTML tags, the content will work on any quarto output format.
+
+## Why quartools?
+
+At work, I ran into an issue where I was generating hundreds of
+parameterised reports that would be similar with subtle differences in
+content. I found myself leaning on R for programmatic markup creation,
+which meant that I could have one master document that I worked on. My
+prototype version (in other words, functions I threw together for work)
+required a lot of constant chunk configuration, and wasn’t particularly
+user-friendly nor elegant. *quartools* is a more streamlined version of
+my prototype, with the added benefit of it requiring little to no setup
+on the end user’s part.
 
 ## Installation
 
-You can install the development version of quartools from
-[GitHub](https://github.com/) with:
+### Release build
+
+``` r
+install.packages('quartools', repos = 'https://elianhugh.r-universe.dev')
+```
+
+### Development build
 
 ``` r
 # install.packages("devtools")
@@ -20,33 +42,64 @@ devtools::install_github("ElianHugh/quartools")
 
 ## Example
 
-This is a basic example which shows you how to solve a common problem:
+### My First Div
+
+The simplest way to create a div block element with quartools is via the
+`div` function. Note that the chunk configuration of `results: asis` is
+not necessary.
 
 ``` r
 library(quartools)
-## basic example code
+div("Hello world!")
+```
+
+<div>
+
+Hello world!
+
+</div>
+
+It is also possible to supply attributes to the div block element via
+the `attr` parameter (the callout will not work on GitHub):
+
+``` r
+div("I'm a tip!", attr = ".callout-tip")
 ```
 
-What is special about using `README.Rmd` instead of just `README.md`?
-You can include R chunks like so:
+<div class="callout-tip">
+
+I’m a tip!
+
+</div>
+
+### Apply
+
+We can leverage the `apply` family of functions ability to loop over
+list elements to simplify creating many divs at once. Normally this
+would require a workaround to allow for printing directly as markdown
+content, but *quartools* exports the `mdapply` function (read: “markdown
+apply”) which allows for directly printing the result as valid markdown
+content.
 
 ``` r
-summary(cars)
-#>      speed           dist       
-#>  Min.   : 4.0   Min.   :  2.00  
-#>  1st Qu.:12.0   1st Qu.: 26.00  
-#>  Median :15.0   Median : 36.00  
-#>  Mean   :15.4   Mean   : 42.98  
-#>  3rd Qu.:19.0   3rd Qu.: 56.00  
-#>  Max.   :25.0   Max.   :120.00
+my_favourite_letters <- letters[1L:3L]
+mdapply(my_favourite_letters, div)
 ```
 
-You’ll still need to render `README.Rmd` regularly, to keep `README.md`
-up-to-date. `devtools::build_readme()` is handy for this.
+<div>
+
+a
+
+</div>
+
+<div>
+
+b
+
+</div>
 
-You can also embed plots, for example:
+<div>
 
-<img src="man/figures/README-pressure-1.png" width="100%" />
+c
 
-In that case, don’t forget to commit and push the resulting figure
-files, so they display on GitHub and CRAN.
+</div>
diff --git a/man/figures/README-pressure-1.png b/man/figures/README-pressure-1.png
diff --git a/man/quartools-package.Rd b/man/quartools-package.Rd