Title

# Literate.jl

## Simple package for literate programming in Julia

Fredrik Ekre, JuliaCon 2019 .right[![](logo.png)]

---

# What is literate programming?

Definition from Wikipedia:

> Literate programming is a programming paradigm [...] in which a program is given as an explanation of the program logic in a natural language, interspersed with snippets of macros and traditional source code, from which a compilable source code can be generated.

Loosely translated by me:

> A program with readable comments that explain the code.

---

# Motivation – What do I want?

* Documenting packages by examples, cf. "example notebooks"

* Examples should be easily testable on CI (no outdated examples)

* Multiple output formats:

* Markdown/HTML pages
      * Jupyter notebooks
      * Julia script files

* Minimal maintenance – one source, one place to make changes

---

# Motivation – What's the problem?

* Maintaining multiple outputs is difficult and they will diverge
  * Notebooks are *really* bad in version control like `git`

* small changes result in unreadable and unreviewable diffs ![](nb-diff.png)
      * too "rich" format, includes large objects like images (often in multiple formats)

---

# Design goals

A `Literate.jl` source file should

* have simple syntax that Julia users are familiar with

* be valid Julia syntax, e.g. a `.jl` file that can be `include`d

* be able to produce multiple outputs – markdown files, notebooks and regular scripts

---

# Design goals

A `Literate.jl` source file should

* have simple syntax that Julia users are familiar with: Julia syntax!

* be valid Julia syntax, e.g. a `.jl` file that can be `include`d: Everything that is not code behind Julia comments (`#`)

* be able to produce multiple outputs – markdown files, notebooks and regular scripts: Multiple source transformations

---

# What does `Literate.jl` offer?

`Literate.jl` provides three functions:

* `Literate.markdown`: Transforms the source file to a markdown file, to be used with e.g. Documenter

* `Literate.notebook`: Transforms the source file to a Jupyter notebook

* `Literate.script`: Transforms the source file to a "pure" Julia script file

---

# Example of a source file

The following code block is an example source file, and also the source block for the upcoming slide

```julia
# # Example of a `Literate.jl` source file
#
# This is a Julia comment, so this is treated as markdown input.
# Here is some **bold text**, and some *text in italic*.
# Let's create a function in a Julia code block

f(x) = 2 * exp(x)
g(x) = 2 * log(x)

# If we plot `f` and `g` with e.g. Plots.jl, the output will be captured

using Plots
x = range(0.0, stop = 2.0, length = 100)
plot(x, [f.(x) g.(x)]; labels = ["f(x) = 2exp(x)" "g(x) = 2log(x)"], legend = :topleft)
```

The upcoming two slides are the output of the the above example.

---

# Example of a `Literate.jl` source file

This is a Julia comment, so this is treated as markdown input. Here is some **bold text**, and some *text in italic*. Let's create a function in a Julia code block

```julia
f(x) = 2 * exp(x)
g(x) = 2 * log(x)
```

```
g (generic function with 1 method)
```

---

If we plot `f` and `g` with e.g. Plots.jl, the output will be captured

```julia
using Plots
x = range(0.0, stop = 2.0, length = 100)
plot(x, [f.(x) g.(x)]; labels = ["f(x) = 2exp(x)" "g(x) = 2log(x)"], legend = :topleft)
```

"/>
<polyline clip-path="url(#clip8702)" style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none" points="
  225.505,1446.71 246.573,1363.3 267.641,1314.51 288.71,1279.89 309.778,1253.04 330.846,1231.1 351.914,1212.55 372.982,1196.48 394.05,1182.31 415.118,1169.63
  436.187,1158.16 457.255,1147.69 478.323,1138.06 499.391,1129.14 520.459,1120.84 541.527,1113.07 562.595,1105.78 583.664,1098.9 604.732,1092.39 625.8,1086.22
  646.868,1080.35 667.936,1074.75 689.004,1069.4 710.072,1064.28 731.141,1059.37 752.209,1054.65 773.277,1050.11 794.345,1045.73 815.413,1041.51 836.481,1037.43
  857.55,1033.48 878.618,1029.66 899.686,1025.96 920.754,1022.37 941.822,1018.88 962.89,1015.49 983.958,1012.19 1005.03,1008.98 1026.09,1005.86 1047.16,1002.81
  1068.23,999.84 1089.3,996.94 1110.37,994.109 1131.44,991.342 1152.5,988.638 1173.57,985.993 1194.64,983.405 1215.71,980.872 1236.78,978.391 1257.84,975.959
  1278.91,973.576 1299.98,971.24 1321.05,968.948 1342.12,966.698 1363.19,964.49 1384.25,962.322 1405.32,960.192 1426.39,958.099 1447.46,956.042 1468.53,954.02
  1489.59,952.031 1510.66,950.074 1531.73,948.149 1552.8,946.253 1573.87,944.388 1594.93,942.551 1616,940.741 1637.07,938.958 1658.14,937.201 1679.21,935.47
  1700.28,933.763 1721.34,932.08 1742.41,930.42 1763.48,928.783 1784.55,927.168 1805.62,925.574 1826.68,924.001 1847.75,922.448 1868.82,920.915 1889.89,919.401
  1910.96,917.907 1932.03,916.43 1953.09,914.971 1974.16,913.53 1995.23,912.106 2016.3,910.699 2037.37,909.308 2058.43,907.932 2079.5,906.573 2100.57,905.228
  2121.64,903.898 2142.71,902.583 2163.77,901.282 2184.84,899.995 2205.91,898.722 2226.98,897.462 2248.05,896.215 2269.12,894.981 2290.18,893.759
  "/>
<polygon clip-path="url(#clip8700)" points="
213.865,312.204 738.72,312.204 738.72,130.764 213.865,130.764
  " fill="#ffffff" fill-rule="evenodd" fill-opacity="1"/>
<polyline clip-path="url(#clip8700)" style="stroke:#000000; stroke-width:4; stroke-opacity:1; fill:none" points="
  213.865,312.204 738.72,312.204 738.72,130.764 213.865,130.764 213.865,312.204
  "/>
<polyline clip-path="url(#clip8700)" style="stroke:#009af9; stroke-width:4; stroke-opacity:1; fill:none" points="
  237.865,191.244 381.865,191.244
  "/>
<g clip-path="url(#clip8700)">
<text style="fill:#000000; fill-opacity:1; font-family:Arial,Helvetica Neue,Helvetica,sans-serif; font-size:48px; text-anchor:start;" transform="rotate(0, 405.865, 208.744)" x="405.865" y="208.744">f(x) = 2exp(x)</text>
</g>
<polyline clip-path="url(#clip8700)" style="stroke:#e26f46; stroke-width:4; stroke-opacity:1; fill:none" points="
  237.865,251.724 381.865,251.724
  "/>
<g clip-path="url(#clip8700)">
<text style="fill:#000000; fill-opacity:1; font-family:Arial,Helvetica Neue,Helvetica,sans-serif; font-size:48px; text-anchor:start;" transform="rotate(0, 405.865, 269.224)" x="405.865" y="269.224">g(x) = 2log(x)</text>
</g>
</svg>

---

# Usage in the wild – `Optim.jl`

`Optim.jl` (package for minimization) uses Literate for some examples in the documentation.

* [Source file](https://github.com/JuliaNLSolvers/Optim.jl/blob/master/docs/src/examples/ipnewton_basics.jl)

* [HTML output](https://julianlsolvers.github.io/Optim.jl/stable/#examples/generated/ipnewton_basics/)

---

# Usage in the wild – `@cormullion`'s blog

Generated with Literate.jl + Thibaut Lienart's (`@tlienart`) [JuDoc.jl](https://github.com/tlienart/JuDoc.jl) package

* [Source file](https://github.com/cormullion/cormullion.github.io/blob/master/src/source/pentachoron.jl)

* [HTML output](https://cormullion.github.io/pub/2019-04-03-pentachoron.html)

---

# Usage in the wild – This presentation

This presentation is generated with `Literate.jl`, and turned into slides using Pietro Vertechi's (`@piever`) [Remark.jl](https://github.com/piever/Remark.jl) package.

---

# Thanks for listening!

---

*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*