Skip to content

Contributing to the Rcpp Gallery

Jump to bottom
jjallaire edited this page Dec 19, 2012 · 20 revisions

Contributions to the Rcpp Gallery are very welcome. To encourage broad use in both open-source and commercial projects, all of the code in the Rcpp Gallery is published under the MIT License.

To contribute an article to the Rcpp Gallery you create a source file containing the C++ and R code along with appropriate context and explanation. Source files can either be plain C++ files (with some special Doxygen comments) or an R Markdown file that includes C++ and R code blocks.

C++ with Doxygen

To create an article using a C++ source file you add an opening comment to the source file containing a pre-defined set of Doxygen fields. For example:

/**
 * @title Modifying a Data Frame
 * @author Dirk Eddelbuettel
 * @license MIT
 * @tags dataframe
 * @summary Demonstrates modifying a data frame passed to a function and 
 *   returning the modified version.
 */

Note that the @license MIT field is required for all submissions and that the @summary field requires indenting if you want to continue it on additional lines.

C++ source files will be processed using the Rcpp::sourceCpp function so can also include embedded R code chunks. For example:

/*** R
df <- data.frame(a = c(1, 2, 3),
                 b = c("x", "y", "z"))
modifyDataFrame(df)
*/

Here are two examples of articles authored using this format:

R Markdown

R Markdown articles can include a mixture of C++ and R code as well as textual content formatted using markdown. R Markdown articles need to include title, author, tags, and summary fields in a --- delimited block at the top of the file:

---
title: Modifying a Data Frame
author: Dirk Eddelbuettel
license: MIT
tags: dataframe
summary: Demonstrates modifying a data frame passed to a function and 
   returning the modified version
---

Note that the license: MIT field is required for all submissions and that the summary field requires indenting if you want to continue it on additional lines.

Within R Markdown documents you can specify that the code inside a chunk is C++ code by specifying the engine='Rcpp' option, for example:

```{r, engine='Rcpp'}

Here is an example of a source file authored using this format: 2012-12-18-simulating-vector-autoregressive-process.Rmd

Submitting an Article

You can submit an article for inclusion in the Rcpp Gallery in one of two ways:

  1. Post your article on the web (e.g. using a Gist) and then submit an issue requesting that we include the article.

  2. Fork the Rcpp Gallery website and submit a pull request with your new or updated articles.

If you are submitting a pull request and;or want to preview what your article will look like once it's published, you'll likely want to clone the Rcpp Gallery repository and setup a local development configuration. Details on doing this are covered in the Development-Setup article.

Clone this wiki locally