-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
170 lines (113 loc) · 5.47 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures",
out.width = "100%"
)
```
<!-- badges: start -->
[](https://CRAN.R-project.org/package=details)
[](https://CRAN.R-project.org/package=details)
[](https://github.com/yonicd/details)
[](https://github.com/yonicd/details)
[](https://github.com/yonicd/details)
[](https://app.codecov.io/gh/yonicd/details?branch=master)
[](http://tinyurl.com/yyodcwc7)
<!-- badges: end -->
# details <img src="man/figures/logo.png" align="right" class="logo" style="height:150px;"/>
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
```md
<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](#markdown) documents and [Roxygen2](#package-documentation) documentation within `R`.
## Installation
### CRAN
``` r
install.packages("details")
```
### Dev
``` r
remotes::install_github("yonicd/details")
```
## Markdown
### Input
The function `details::details` can handle inputs
- R object with supported classes:
- `character`
- `data.frame`
- `tibble`
- `list`
- `device` (eg plots)
- File paths will be identified internally and the lines will be read in automatically.
### Output
The function `details::details` can output the result to
- console (default)
- clipboard via [clipr](https://github.com/mdlincoln/clipr)
- [file.editor](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/file.edit.html) useful when clipr not available
### Examples
One the most popular uses for `details` is to paste the sessioninfo at the bottom of a GitHub issue.
```{r}
library(details)
sessioninfo::session_info()%>%
details::details(summary = 'current session info')
```
You can also use the `knitr` chunk engine that is shipped with `details` to created outputs in `Rmarkdown` documents.
````markdown
`r ''````{details, echo = FALSE, details.summary = 'current session info'}
sessioninfo::session_info()
```
````
```{details, echo = FALSE, details.summary = 'current session info'}
sessioninfo::session_info()
```
There are a [number of objects](https://yonicd.github.io/details/articles/objects.html) 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
```{r}
details(plot(x=mtcars$mpg,y=mtcars$wt), summary = 'My plot')
```
## Package Documentation
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)
### Setup
To make it easy to set up the DESCRIPTION file of your package so you can use `details` macros run the following :
``` r
use_details('PATH_TO_DESCRIPTION_FILE')
```
This will append three elements to the DESCRIPTION file
- Imports: details
- RdMacros: details
- Roxygen: list(markdown = TRUE)
### Usage
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 <svg style="height:0.8em;top:.04em;position:relative;" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg> __SUMMARY TEXT__.
The default will display <svg style="height:0.8em;top:.04em;position:relative;" viewBox="0 0 192 512"><path d="M0 384.662V127.338c0-17.818 21.543-26.741 34.142-14.142l128.662 128.662c7.81 7.81 7.81 20.474 0 28.284L34.142 398.804C21.543 411.404 0 402.48 0 384.662z"/></svg> __details__.
These folded blocks can be inserted anywhere in the documentation, eg `@description`, `@param`, `@details`, `@return`, ....
## Vignettes
More information can be found in the [articles](https://yonicd.github.io/details/) of the package site.
- Creating a sessioninfo to paste into Github, Stackoverflow or Community Sites.
- Customizing the details output
- What R objects details can handle
- Using the details knitr chunk engine
- Using details in Roxygen2
## Code of Conduct
Please note that the 'details' project is released with a
[Contributor Code of Conduct](https://github.com/yonicd/details/blob/master/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.