Contributing to the Rcpp Gallery

JJ Allaire edited this page Nov 13, 2015 · 18 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 and which follows Rcpp Gallery conventions:
    1. Rcpp namespace should be globally available ("using namespace Rcpp;"); and
    2. Other namespaces (e.g. R, std, arma, etc.) should be explicitly qualified.
  • 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/

Formatting

Features

Mathematical expressions can be included in R Markdown files and will now be rendered by MathJax. To use this functionality, the mathjax: true field is required, as below.

---
title: Modifying a Data Frame
author: Dirk Eddelbuettel
license: GPL (>= 2)
tags: dataframe
mathjax: true
summary: Demonstrates modifying a data frame passed to a function and
returning the modified version

---

Next, you need to format your mathematical expressions in a way that is expected. For inline math using LaTeX markup like

The equation $$ \hat{\beta} = {X'X}^{-1}X'y $$ makes a good tattoo.

or

The equation
$$ \hat{\beta} = {X'X}^{-1}X'y $$
makes a good tattoo.

For display math, you would use

The equation

$$ \hat{\beta} = {X'X}^{-1}X'y $$

makes a good tattoo.

There are some issues with tables and the | character, though. These can be avoided by using \vert and not |.

Conventions

Contributors will usually use headings of different levels in their posts and in markdown this might look like the following:

# my top level heading
some text

## a subsection
more text

# another top level heading
still yet, more text

However, so the generated HTML file is styled correctly, the convention is to have top level headings at ##, not #. The correct version of the above snippet is as follows:

## my top level heading
some text

### a subsection
more text

## another top level heading
still yet, more text

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.