Skip to content

How to document Processing.R

Jump to bottom
Jeremy Douglass edited this page Aug 2, 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.

The E2E Test Generator Tool

A reference entry is a function or variable etc. along with a description, an example code sketch, and an image illustrating the output.

When a properly formed reference example is created in examples/reference then the E2E Test Generator Tool will generate both documentation and an e2e test case. The test confirms that, when run, the reference example code will generate the reference image. If example code produces an image that does not match the reference, the test fails.

Reference structure

The structure of examples/reference should be:

examples/
  reference/
    <function-name>/
      .property.yml
      <function-name>1/
        .test.yml
        <function-name>1.rpde
      <function-name>2/
      ...

YML file structure

.property.yml

The structure of .property.yml, see examples/reference/arc/.property.yml as a example:

category: <category of the functino>
subcategory: <subcategory of the function>
description: <descriptinon of the function>
syntax: <syntax of the function>
parametes:
  - label: <name of the parameter>
    description: <description of the parameter>
  - ...
related:
  - <name of related function>
  - ...

.test.yml

test:
  reference: <URL to the png of the example>

Categories and subcategories

These are taken from the Processing Reference. They are:

  • Structure
  • Environment
  • Data
    • Primitive
    • Composite
    • Conversion
    • String Functions
    • Array Functions
  • Control
    • Relational Operators
    • Iteration
    • Conditionals
    • Logical Operators
  • Shape
    • 2D Primitives
    • Curves
    • 3D Primitives
    • Attributes
    • Vertex
    • Loading & Displaying
    • Input
    • Mouse
    • Keyboard
    • Files
    • Time & Date
  • Output
    • Text Area
    • Image
    • Files
  • Transform
  • Lights, Camera
    • Lights
    • Camera
    • Coordinates
    • Material Properties
  • Color
    • Setting
    • Creating & Reading
  • Image
    • Loading & Displaying
    • Textures
    • Pixels
    • Rendering
    • Shaders
  • Typography
    • Loading & Displaying
    • Attributes
    • Metrics
  • Math
    • Operators
    • Bitwise Operators
    • Calculation
    • Trigonometry
    • Random
  • Constants

Where to start

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