Workflow

[ramnathv]

These are some notes as I brainstorm on the best workflow for documentation.

Current

1. Write documentation in Rrst.
2. Knit to rst.
3. Use sphinx to generate the documentation.

Since the pdf version does not pick up iframes, there is a manual step here that involves using SVG Crowbar to download a plot as svg, print it to pdf, crop out the non-chart portions, save it in the _downloads directory and add a link in the Rrst with the directive .. only:: latex.

[ramnathv]

Approach 1: Separate Code from Docs

One possibility I have been toying around with is to separate the process of creating the charts from the actual documentation. While reproducible documentation is fun, I often find myself tweaking things indefinitely, which distracts away from the actual documentation. From a productivity perspective, I see merit in separating the writing from the coding, since the two tasks involve different approaches.

Here is one way to adopt this workflow.

1. Write examples in .R files.
2. Create HTML charts and either save them or upload to gist.
3. Create PDF/SVG version of charts for static documentation.
4. Put everything in a folder so that it becomes a self-contained example unit.

Now, I can write R code to read the example folder and generate the necessary reSt tags that would display the example optimally in multiple formats. This approach has the advantage that users can contribute simple examples that I can seamlessly integrate into my documentation.