https://github.com/kickstarter/kumquat
Kumquat is a Rails Engine for rendering RMarkdown files.
https://github.com/kickstarter/kumquat
Last synced: about 1 year ago
JSON representation
Kumquat is a Rails Engine for rendering RMarkdown files.
- Host: GitHub
- URL: https://github.com/kickstarter/kumquat
- Owner: kickstarter
- License: mit
- Created: 2015-03-31T19:11:01.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2018-05-23T15:13:34.000Z (about 8 years ago)
- Last Synced: 2025-04-30T04:48:48.752Z (about 1 year ago)
- Language: Ruby
- Size: 53.7 KB
- Stars: 43
- Watchers: 127
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# Kumquat
Kumquat is a reporting tool for rendering [RMarkdown](http://kbroman.org/knitr_knutshell/pages/Rmarkdown.html) files inside Rails.
RMarkdown, or `.Rmd` files are Markdown files with code chunks of [R](http://r-project.org/) in them.
You can use Kumquat to integerate R output into Rails, which is useful for using libaries like `ggplot2` in email reporting tools.
# Example
For example, consider a typical `render` call to a partial:
`render '_a_knitr_report'`
This partial is `_a_knitr_report.Rmd`, a regular RMarkdown file stored in your app:
```md
A Test Report for Kumquat
========================================================
This is some code for Knitr, including [a link](https://www.kickstarter.com).
A list:
* One
* Another thing
* Last thing!
### More stuff.
Lorem Ipsum.
```{r, fig.width=10, fig.height=8, echo=FALSE, message=FALSE}
library(ggplot2)
qplot(data = data.frame( x = runif(100), y = runif(100) ), x = x, y = y)
```
```
Which yields the following output:
Kumquat can be integrated anywhere inside Rails views where partials are called.
# How it Works
Kumquat requires R to be installed on the machines running your application. The main action is then in `Knit2HTML` which shells out to `Rscript` and runs the necessary `knitr` package methods to compile HTML.
When you install Kumquat a template handler is registered to handle Rmd files.
# Also, Email
A mail interceptor, `KumquatReportInterceptor` is also registered to attach images inline to Rmd reports marked with an `X-KUMQUAT` signature which you can add to a mail object accordingly:
```ruby
mail :to => @admin.email,
:reply_to => "dev@kickstarter.com",
:subject => "Test Kumquat Report",
'X-KUMQUAT' => true do |format|
format.text { render layout: nil }
format.html { render layout: nil }
end
```
# Setup & Development
Kumquat requires R to be installed, and the knitr packages to render RMarkdown files. The rest of the R dependencies are up to you, but need to be specified in the `KNITR_LIBRARIES` constant in the `Knit2HTML` class.
## Chef Recipe
If you're curious about installing R using Chef, check out [a suggested recipe on the wiki](https://github.com/kickstarter/kumquat/wiki/Suggested-Chef-Recipe)
## Database Support
If you need to connect R to a database and provide credentials from your application, you can do so in an application initializer like so:
```ruby
Kumquat.database_config(Configs[:redshift].merge({ database_connector: "RPostgres::Postgres()" }))
```
We are using Hadley Wickham's [RPostgres library](https://github.com/rstats-db/RPostgres) which can be installed in R accordingly:
```R
install.packages("devtools")
devtools::install_github("RcppCore/Rcpp")
devtools::install_github("rstats-db/DBI")
devtools::install_github("rstats-db/RPostgres")
library(DBI)
```
## Sending emails from a local development environment
If you'd like to deliver emails in your local environment, make sure your `config.action_mailer.delivery_method` is configured properly, and you have a way to send email locally (on OS X, run the command `sudo postfix start`).
## Logging
You can view kumquat and email logs for debugging `tail -f log/kumquat.log`