Editing Reproducible computational experiments using SCons (section)

==Creating reproducible documentation==

You are done with computational experiments and want to communicate
them in a paper. SCons helps us create high-quality papers where
computational results (figures) are integrated with papers written in
L<sup>A</sup>TEX\. 
The corresponding SCons extension is defined in  <tt>&#36;PYTHONPATH/rsf/tex.py</tt> where
<tt>RSFROOT</tt> is the environmental variable to the Madagascar
installation directory. The source of this file is in
[http://sourceforge.net/p/rsf/code/HEAD/tree/trunk/framework/rsf/tex.py framework/rsf/tex.py].
We summarize the basic methods and commands in the tables.

{| class="wikitable"
|+Basic methods of an <tt>rsf.tex</tt> object.
|- 
|style="background-color:#ffdead;"| '''<tt>Paper(paper_name,[,lclass][,use][,include][,options])</tt>'''
|-
| A rule to compile <tt><math><</math>paper_name<math>></math>.tex</tt> L<sup>A</sup>TEX\ document using the L<sup>A</sup>TEX2e class specified in <tt>lclass</tt> (default is <tt>geophysics.cls</tt> from the [[SEGTeX]] package) with additional options specified in <tt>options</tt>,  additional packages specified in <tt>use</tt>, and additional preamble specified in <tt>include</tt>. 
|- 
|style="background-color:#ffdead;"| '''<tt>End()</tt> '''
|-
| A rule to collect default targets (referring to <tt>paper.tex</tt> document).
|}

{| class="wikitable"
|+SCons commands defined in <tt>rsftex</tt>.
|- 
|style="background-color:#ffdead;"| '''<tt>scons</tt>'''
|-
| Generate the default target (usually the PDF file <tt>paper.pdf</tt> from the source L<sup>A</sup>TEX file <tt>paper.tex</tt>.) 
|- 
|style="background-color:#ffdead;"| '''<tt>scons pdf</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.pdf</tt> '''
|-
| Generate PDF files from L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt>. 
|- 
|style="background-color:#ffdead;"| '''<tt>scons read</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.read</tt> '''
|-
| Generate PDF files from L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and display them on the screen. 
|- 
|style="background-color:#ffdead;"| '''<tt>scons print</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.print</tt> '''
|-
| Generate PDF files from L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and print them. 
|- 
|style="background-color:#ffdead;"| '''<tt>scons html</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.html</tt> '''
|-
| Generate HTML files from L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> using L<sup>A</sup>TEXtoHTML. The directory <tt><math><</math>paper_name<math>></math>_html</tt> gets created. 
|- 
|style="background-color:#ffdead;"| '''<tt>scons install</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.install</tt> '''
|-
| Generate PDF and HTML files from L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> and install them in a separate location (used for publishing on a web site).
|- 
|style="background-color:#ffdead;"| '''<tt>scons wiki</tt>''' or '''<tt>scons <math><</math>paper_name<math>></math>.wiki</tt> '''
|-
| Convert L<sup>A</sup>TEX sources <tt>paper.tex</tt> or <tt><math><</math>paper_name<math>></math>.tex</tt> to the <tt>MediaWiki</tt> format (used for publishing on a Wiki web site). 
|}

<!-- 
A Madagascar reproducible paper is a paper written in L<sup>A</sup>TEX and
whose figures are either generated by Madagascar reproducible scripts
or available for download, e.g., this paper!  (<tt>paper.tex</tt>
available in the <tt>rsf/scons/</tt> directory of Madagascar book
section).

The main SConstruct command set in our reproducible research
environment and related to documentation is

This command is defined in <tt>&#36;PYTHONPATH/rsf/tex.py</tt>.
 -->

===Example===

This paper by itself is an example of a reproducible document. It is
generated using the following <tt>SConstruct</tt> file which is place
in the directory above the projects directories.

<syntaxhighlight lang="python">
from rsf.tex import *
Paper('velan',use='hyperref,listings,color')
End(use='hyperref,listings,color')
</syntaxhighlight>


This <tt>SConstruct</tt> generates this paper, but it can also compile
<tt>velan.tex</tt> in the same directory. Note that there is no
<tt>Paper</tt> command for <tt>paper.tex</tt> since it is the default
documentation name. Optional L<sup>A</sup>TEX packages and style used in
<tt>paper.tex</tt> are passed in the End command.

Let's now take a closer look at <tt>paper.tex</tt> to understand how
the figures of the documentation are linked to the reproducible
scripts that created them. First of all, note that <tt>paper.tex</tt>
is not a regular L<sup>A</sup>TEX document but only its body (no
<math>\backslash</math>documentclass, <math>\backslash</math>usepackage, etc.). In our
paper, the first figure was created in the project folder
<tt>easystart</tt> (sub-folder of our documentation folder) by the
resulting plot <tt>lena.vpl</tt>. In the L<sup>A</sup>TEX source code, it
translates as

<syntaxhighlight lang="latex">
\inputdir{easystart} 
\sideplot{lena}{height=.25\textheight}{The output of the first numerical experiment.}
</syntaxhighlight>

The <math>\backslash</math>inputdir command points to the project directory and
the <math>\backslash</math>sideplot command calls <tt><math><</math>result_name<math>></math></tt>. The
L<sup>A</sup>TEX tag of the figure is <tt>fig:<math><</math>result_name<math>></math></tt>. The
first time the paper is compiled, the result file is automatically
converted to PDF format. 

<!-- 
===Useful SCons commands for reproducible documentation===

To compile this paper, you first need to run and lock the
<tt>easystart</tt> project. Go in the <tt>easystart</tt> folder and
run <tt>scons lock</tt>. Go back to the documentation folder and run
<tt>scons pdf</tt> (alternatively \texttt{scons
  <math><</math>paper_name<math>></math>.pdf}). Use <tt>scons read</tt> (alternatively
<tt>scons <math><</math>paper_name<math>></math>.read</tt>) or your favorite PDF reader to
read this paper reproduced by yourself...
 -->