Improving the ggplot2 documentation

Note: The ggplot2 wiki is no longer maintained, please use the ggplot2 website instead!

Improving the ggplot2 documentation

Thanks for being interested in improving ggplot2! To get started, you first need to have a github account, so before you get started, make sure to sign up for a free account.

There are two ways to contribute, described below:

• A few small changes.
• Many, bigger changes.

These instructions are a work in progress. If you have any confusion, please email the ggplot2 documentation mailing list.

A few small changes

If you want to make a small change to the documentation (like fixing a typo), you can edit the documentation comments directly online. Go to the master branch of ggplot2, and find the file that corresponds to the function you want to modify. (This is usually pretty easy: the documentation for geom_point is in geom-point.R). Then:

1. Click "fork and edit this file"
2. Edit the file in your web browser
3. Click "propose file change"
4. Write a v. brief description of your changes (e.g. fix typos)
5. Click "send pull request"

A bigger commitment

If you'd like to make more or bigger changes, you'll need to get set up with a ggplot2 development environment. This is quite a lot of work, but you can always get in touch via email and I'll help you if you get stuck.

Firstly, you need to make sure you're set up to develop packages. This is platform specific:

• On windows, download and install Rtools
• On the mac, make sure you have xcode installed
• On linux, make sure you have the R-dev packages installed

You can check everything is installed correctly with the has_devel function from the devtools package. You'll also need this for other development tasks, so install it and check that you're good to go:

install.packages(c("devtools", "RCurl"))    
library(devtools)
has_devel()

If everything is installed correctly, the function will print some output and then return TRUE.

After installing devtools from CRAN (version .3) you'll need to use devtools to upgrade to the development version:

install_github("devtools")

Restart R and recheck devtools with

library(devtools)
has_devel()

Next, you'll need to fork a copy of the ggplot2 repository. A fork gives you your own version of all the ggplot2 source code - here you can make changes and then submit them to the ggplot2 development team for inclusion in the released version.

Once you have a fork, you need to get a copy of the source code on your local computer. If you haven't used git before, I'd recommend starting with smartgit, which is a nice GUI free for non-commercial use. You then need to clone your fork on your local computer, and make sure that you're in the develop branch.

Next, you need to install the development version of roxygen, the tool used to convert documentation comments into the Rd files needed for R packages. You also need the scales package which is not yet on CRAN. Installing both is easy with devtools:

library(devtools)
install_github("roxygen", "klutometis")
install_github("scales")

Check that you're all set up by running

document("path/to/ggplot2")

which will rebuild the documentation. Install the development version by first turning dev_mode() on (so this install of ggplot2 doesn't interfere with your current install) and then running install:

dev_mode() # only need to do once per session
document("path/to/ggplot2") # make sure docs are up-to-date
install("path/to/ggplot2")

You'll repeat these steps multiple times so when you modify the documentation you can check that your changes look ok.