| title | tags | authors | affiliations | date | bibliography | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Lepton: An automaton for Literate Executable Papers |
|
|
|
12 July 2018 |
biblio_lepton.bib |
Source code is very hard to maintain when the documentation is missing. Recognizing this fact, D. Knuth [@Knuth84literateprogramming] proposed the literate programming paradigm, i.e. that source code and documentation should be written at the same time, inside the same file, and in a format designed for human understanding.
''Lepton'' adds documents such as data analysis reports and scientific papers to this vision. To enable reproducible research, ''Lepton'' makes it easy to include scripts or complete programs, compilation and execution instructions, as well as execution results in the same file. Offloading execution to ''Lepton'' makes the analysis operator-independent and easy to reproduce. In the spirit of literate programming, the plain text file format used by ''Lepton'' is intended to be human-understandable as opposed to machine-readable, and simple enough to be usable without the software.
''Lepton'' consists in a standalone executable that processes plain text files written in a documentation format such as HTML or LaTeX with optional blocks that can contain files to be written to disk, source code or executable instructions. It is distributed as a ''Lepton'' file containing the full source code, manual and a tutorial. The package contains an extracted copy of the source code that can be compiled without ''Lepton''.
lepton_manual.pdfcontains usage instructionslepton.pdfcontains the implementation details.
The root directory contains all the necessary files for using Lepton:
- The
lepton.binexecutable can be compiled with the includedmake.shscript. - The
lepton.styfile is useful for producing files in LaTeX together with code highlighting with the Pygments library. Thelepton.bibfile contains references in BibTeX format.
Requirements
- OCaml > 4.0
Three examples are provided :
hello.nwis a minimal working example showing how to embed OCaml source code and execute it. It requires only LaTeX and OCaml. See Section 1 oflepton_manual.pdffor details.fibonacci.nwis an example of a scientific report comparing several implementations of the Fibonacci sequence and their running times. The corresponding rendered PDFfibonacci.pdfcontains instructions on how to execute it. It has the same requirements as "Boostrapping".lepton.nwis the source file used for the source code and the documentation of Lepton. Executing this example will regenerate both the binary executable and the PDF documentation. The process is described in the "Bootstrapping" section of this document and inlepton.pdf.
All the provide files can be re-generated from the file lepton.nw in the bootstrap directory.
This will produce a new executable, extract copies of the source files.
Continuous Integration is defined in .gitlab-ci.yml and run on PLMLab
Requirements
- LaTeX
- Pygments for syntax highlighting and the
mintedLaTeX package
Steps :
- rename the executable, e.g.
mv lepton.bin lepton. (the next command will runmake.shand attempt to overwritelepton.bin) - process the main source file with Lepton
./lepton lepton.nw -o lepton.tex - (optional) compile the re-generated documentation with LaTeX
xelatex -shell-escape -8bit lepton.tex
bibtex lepton.aux
xelatex -shell-escape -8bit lepton.tex
xelatex -shell-escape -8bit lepton.tex # LaTeX needs to execute twice to resolve references
If you wish to report bugs, please use the issue tracker at Github. If you would like to contribute to Lepton, just open an issue or a merge request.
We use the following Docker images in this project
- ocamlpro/ocaml:4.14 : Alpine Linux with OCaml, just enough for compiling lepton
- lepton + python : for testing the markdown formatter and python chunks
- lepton + debian + latex : for producing PDF documentation