Skip to content

How to document Processing.R

Jeremy Douglass edited this page Jun 15, 2017 · 5 revisions

Please help migrate documentation from Processing to Processing.R by following these instructions.

Overview

The process is:

  1. Choose an undocumented reference folder containing no example subfolders, e.g. /examples/reference/ambient/
  2. Look up the Processing(Java) reference page, e.g. https://processing.org/reference/ambient_.html
  3. Document the reference by updating .property.yml -- existing content may be imported from Processing.py and need updating to Processing.R details
  4. Add Example(s) for each example appearing in the Processing(Java) reference:
    1. add an example subfolder and name-matching .rpde file, e.g. /examples/reference/ambient/ambient0/ambient0.rpde
    2. translate the Processing(Java) example into the Processing.R equivalent in the .rpde file
    3. if the Processing(Java) reference example has an image:
      1. add a test configuration by creating a .test.yml file pointing to that image

Details

First choose a function or keyword that is not documented in Processing.R. This will be a folder in /master/examples/reference that contains only a .yml file, or nothing (no example folders. It corresponds to a reference keyword on the Processing Reference page. We will be translating the example code sketches from that reference into R and added tests to confirm that the R documentation will generate the same visual output as the official reference.

As an example:

  1. Choose a function or keyword. We choose: ambient.
  2. Add a new folder in the corresponding folder: Create ambient0 in examples/reference/ambient, which means that this is the first example for ambient.
  3. Create two files in the folder, one is .test.yml, and the other is ambient0.rpde. In ambient0.rpde you should put the example code, and in .test.yml you need to put the link to example's image in Processing.org.

In this case, the original Processing(Java) code from the ambient reference is:

size(100, 100, P3D);
background(0);
noStroke();
directionalLight(153, 153, 153, .5, 0, -1);
ambientLight(153, 102, 0);
ambient(51, 26, 0);
translate(70, 50, 0);
sphere(30);

...so the new Processing.R code in ambient0.rpde should be:

P3D <- "processing.opengl.PGraphics3D"

settings <- function() {
    size(100, 100, P3D)
}

draw <- function() {
    background(0)
    noStroke()
    directionalLight(153, 153, 153, 0.5, 0, -1)
    ambientLight(153, 102, 0)
    ambient(51, 26, 0)
    translate(70, 50, 0)
    sphere(30)
}

You can see it is a little different since this is written in R. Most of the differences are minor, such as no semicolons.

One big difference is that many Processing(Java) sketches are not defined instide settings() setup() or draw() functions -- they are instead written as a simple series of statements in "immediate mode." Processing.R however currently needs to use settings() and draw() in order to call size() or set up the 3D mode correctly.

The code in .test.yml should be:

test:
  reference: https://processing.org/reference/images/ambient_.png

Finally, run ./hack/generate-e2e-test.py to generate e2e test cases for your change and run ant test to test it. If it passes, you have added a new item for Processing.R documentation.

You can start from these functions since it is simple.

applyMatrix()
popMatrix()
printMatrix()
pushMatrix()
resetMatrix()
rotate()
rotateX()
rotateY()
rotateZ()
scale()
shearX()
shearY()
translate()
Clone this wiki locally