Skip to content

Contributing to the Rcpp Gallery

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

Contributions to the Rcpp Gallery are very welcome. To contribute an article you create a source file containing 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

You can author articles by simply creating a C++ source file with Doxygen comments. These source files are processed using Rcpp::sourceCpp so can easily export their functions to R and then include R code chunks to demonstrate their use.

To start with, 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 GPL (>= 2)
 * @tags dataframe
 * @summary Demonstrates modifying a data frame passed to a function and 
 *   returning the modified version.
 */

Note that the @license GPL (>= 2) field is required for all submissions and that the @summary field requires indenting if you want to continue it on additional lines.

The remainder of the file contains a mix of the following:

  • Freestanding C++ code that will be compiled using sourceCpp
  • Additional Doxygen-style comment blocks (e.g. starting with /**) that will be converted to HTML in published articles.
  • R code chunks that will be sourced and run by sourceCpp

Here's an example of including an embedded R code chunk:

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

Here's an example of C++ source file created using these conventions: 2012-14-14-modifying-a-data-frame.cpp.

Invoking make compiles this source file and converts it into this article on the website: http://gallery.rcpp.org/articles/modifying-a-data-frame/

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: GPL (>= 2)
tags: dataframe
summary: Demonstrates modifying a data frame passed to a function and 
   returning the modified version
---

Note that the license: GPL (>= 2) 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

Invoking make compiles the Rmd file and converts it into this article on the website: http://gallery.rcpp.org/articles/simulating-vector-autoregressive-process/

Submitting an Article

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

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

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

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 Local-Development-Configuration article.

Clone this wiki locally