Suppose you’re opening an issue in GitHub and there’s a lot noisey
logs that may be useful or you want to add the
sessionInfo()
to the end of the issue.
Rather than wrecking readability, wrapping it in a
<details>
tag is a great solution
<details>
<summary>Summary Goes Here</summary>
...this is hidden, collapsable content...</details>
Doing this manually every time is a pain.
details
is a package lets you create and customize
details blocks for markdown documents and Roxygen2 documentation within
R
.
install.packages("details")
::install_github("yonicd/details") remotes
The function details::details
can handle inputs
character
data.frame
tibble
list
device
(eg plots)The function details::details
can output the result
to
One the most popular uses for details
is to paste the
sessioninfo at the bottom of a GitHub issue.
library(details)
::session_info()%>%
sessioninfo::details(summary = 'current session info') details
─ Session info ───────────────────────────────────────────────────────────────
setting value 4.1.0 (2021-05-18)
version R version 10.16
os macOS Big Sur .0
system x86_64, darwin17
ui X11 language (EN)
-8
collate en_US.UTF-8
ctype en_US.UTF/New_York
tz America2022-03-27
date
─ Packages ───────────────────────────────────────────────────────────────────* version date lib source
package 3.2.0 2022-02-14 [1] standard (@3.2.0)
cli 0.7.1 2020-10-08 [1] standard (@0.7.1)
clipr 1.4.1 2022-03-06 [1] standard (@1.4.1)
desc * 0.2.1 2020-01-12 [1] standard (@0.2.1)
details 0.6.27 2020-10-24 [1] standard (@0.6.27)
digest 0.14 2019-05-28 [1] standard (@0.14)
evaluate 1.1.0 2021-01-25 [1] standard (@1.1.0)
fastmap 0.5.2 2021-08-25 [1] standard (@0.5.2)
htmltools 1.4.2 2020-07-20 [1] standard (@1.4.2)
httr 1.37 2021-12-16 [1] standard (@1.37)
knitr 2.0.1 2020-11-17 [1] standard (@2.0.1)
magrittr 0.1-7 2013-12-03 [1] standard (@0.1-7)
png 2.5.0 2020-10-28 [1] standard (@2.5.0)
R6 0.4.11 2021-04-30 [1] standard (@0.4.11)
rlang 2.13 2022-03-10 [1] standard (@2.13)
rmarkdown 2.0.2 2020-11-15 [1] standard (@2.0.2)
rprojroot 0.13 2020-11-12 [1] standard (@0.13)
rstudioapi 1.1.1 2018-11-05 [1] CRAN (R 4.1.0)
sessioninfo 1.7.6 2021-11-29 [1] standard (@1.7.6)
stringi 1.4.0 2019-02-10 [1] standard (@1.4.0)
stringr 2.5.0 2022-03-03 [1] standard (@2.5.0)
withr 0.30 2022-03-02 [1] standard (@0.30)
xfun 1.3.2 2020-04-23 [1] standard (@1.3.2)
xml2 2.3.5 2022-02-21 [1] standard (@2.3.5)
yaml
1] /Users/yonis/Library/R/x86_64/4.1/library
[2] /Library/Frameworks/R.framework/Versions/4.1/Resources/library [
You can also use the knitr
chunk engine that is shipped
with details
to created outputs in Rmarkdown
documents.
```{details, echo = FALSE, details.summary = 'current session info'}
sessioninfo::session_info()
```
─ Session info ───────────────────────────────────────────────────────────────
setting value 4.1.0 (2021-05-18)
version R version 10.16
os macOS Big Sur .0
system x86_64, darwin17
ui X11 language (EN)
-8
collate en_US.UTF-8
ctype en_US.UTF/New_York
tz America2022-03-27
date
─ Packages ───────────────────────────────────────────────────────────────────* version date lib source
package 3.2.0 2022-02-14 [1] standard (@3.2.0)
cli 0.7.1 2020-10-08 [1] standard (@0.7.1)
clipr 1.4.1 2022-03-06 [1] standard (@1.4.1)
desc * 0.2.1 2020-01-12 [1] standard (@0.2.1)
details 0.6.27 2020-10-24 [1] standard (@0.6.27)
digest 0.14 2019-05-28 [1] standard (@0.14)
evaluate 1.1.0 2021-01-25 [1] standard (@1.1.0)
fastmap 0.5.2 2021-08-25 [1] standard (@0.5.2)
htmltools 1.4.2 2020-07-20 [1] standard (@1.4.2)
httr 1.37 2021-12-16 [1] standard (@1.37)
knitr 2.0.1 2020-11-17 [1] standard (@2.0.1)
magrittr 0.1-7 2013-12-03 [1] standard (@0.1-7)
png 2.5.0 2020-10-28 [1] standard (@2.5.0)
R6 0.4.11 2021-04-30 [1] standard (@0.4.11)
rlang 2.13 2022-03-10 [1] standard (@2.13)
rmarkdown 2.0.2 2020-11-15 [1] standard (@2.0.2)
rprojroot 0.13 2020-11-12 [1] standard (@0.13)
rstudioapi 1.1.1 2018-11-05 [1] CRAN (R 4.1.0)
sessioninfo 1.7.6 2021-11-29 [1] standard (@1.7.6)
stringi 1.4.0 2019-02-10 [1] standard (@1.4.0)
stringr 2.5.0 2022-03-03 [1] standard (@2.5.0)
withr 0.30 2022-03-02 [1] standard (@0.30)
xfun 1.3.2 2020-04-23 [1] standard (@1.3.2)
xml2 2.3.5 2022-02-21 [1] standard (@2.3.5)
yaml
1] /Users/yonis/Library/R/x86_64/4.1/library
[2] /Library/Frameworks/R.framework/Versions/4.1/Resources/library [
There are a number of objects that can be placed in a details block other than a character object. An example of a object is a device output such as a plot
details(plot(x=mtcars$mpg,y=mtcars$wt), summary = 'My plot')
Many times in documentation there is a lot to say, but you do not want to overwhelm the user.
To solve this we can use folding blocks in the documentation (which are then rendered into pkgdown website automatically)
To make it easy to set up the DESCRIPTION file of your package so you
can use details
macros run the following :
use_details('PATH_TO_DESCRIPTION_FILE')
This will append three elements to the DESCRIPTION file
You can use this feature by wrapping documentation with the macros
\foldstart{[SUMMARY TEXT]}
#' DOCUMENTATION
#' ...
#' DOCUMENTATION
\foldend
The SUMMARY_TEXT
is optional, where the folded block
will have a header of
SUMMARY TEXT.
The default will display details.
These folded blocks can be inserted anywhere in the documentation, eg
@description
, @param
, @details
,
@return
, ….
More information can be found in the articles of the package site.
Please note that the ‘details’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.