summaryrefslogtreecommitdiff
path: root/README.md
blob: 3e2a54044d5cfe39ae3f8f29241df42b1bed936d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
# pandoc-plot 

## A Pandoc filter to generate figures from code blocks in documents

[![Hackage version](https://img.shields.io/hackage/v/pandoc-plot.svg)](http://hackage.haskell.org/package/pandoc-plot) [![Stackage version (nightly)](http://stackage.org/package/pandoc-plot/badge/nightly)](http://stackage.org/nightly/package/pandoc-plot) [![Build status](https://ci.appveyor.com/api/projects/status/mmgiuk52j356e6jp?svg=true)](https://ci.appveyor.com/project/LaurentRDC/pandoc-plot) [![Build Status](https://dev.azure.com/laurentdecotret/pandoc-plot/_apis/build/status/LaurentRDC.pandoc-plot?branchName=master)](https://dev.azure.com/laurentdecotret/pandoc-plot/_build/latest?definitionId=5&branchName=master) ![GitHub](https://img.shields.io/github/license/LaurentRDC/pandoc-plot) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pandoc-plot.svg)](https://anaconda.org/conda-forge/pandoc-plot)

`pandoc-plot` turns code blocks present in your documents (Markdown, LaTeX, etc.) into embedded figures, using your plotting toolkit of choice, including Matplotlib, ggplot2, MATLAB, Mathematica, and more.

## Table of content

* [Usage](#usage)
* [Supported toolkits](#supported-toolkits)
* [Features](#features)
    * [Captions](#captions)
    * [Link to source code](#link-to-source-code)
    * [Preamble scripts](#preamble-scripts)
    * [No wasted work](#no-wasted-work)
    * [Compatibility with pandoc-crossref](#compatibility-with-pandoc-crossref)
* [Configuration](#configuration)
    * [Toolkit-specific options](#toolkit-specific-options)
* [Usage as a Haskell library](#usage-as-a-haskell-library)
* [Installation](#installation)
* [Warning](#warning)

## Usage

This program is a [Pandoc](https://pandoc.org/) filter. It operates on the Pandoc abstract syntax tree, and can therefore be used in the middle of conversion from input format to output format.

The filter recognizes code blocks with classes that match plotting toolkits. For example, using the `matplotlib` toolkit:

~~~markdown
# My document

This is a paragraph.

```{.matplotlib}
import matplotlib.pyplot as plt

plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')
```
~~~

Putting the above in `input.md`, we can then generate the plot and embed it in an HTML page:

```bash
pandoc --filter pandoc-plot input.md --output output.html
```

*Note that pandoc-plot only works with pandoc >= 2.8 because of some breaking changes in pandoc's API.*

## Supported toolkits

`pandoc-plot` currently supports the following plotting toolkits (**installed separately**):

* `matplotlib`: plots using the [matplotlib](https://matplotlib.org/) Python library;
* `plotly_python` : plots using the [plotly](https://plot.ly/python/) Python library;
* `matlabplot`: plots using [MATLAB](https://www.mathworks.com/);
* `mathplot` : plots using [Mathematica](https://www.wolfram.com/mathematica/);
* `octaveplot`: plots using [GNU Octave](https://www.gnu.org/software/octave/);
* `ggplot2`: plots using [ggplot2](https://ggplot2.tidyverse.org/);
* `gnuplot`: plots using [gnuplot](http://www.gnuplot.info/);


To know which toolkits are useable on *your machine* (and which ones are not available), you can check with the `--toolkits/-t` flag:

```bash
pandoc-plot --toolkits
```

**Wish your plotting toolkit of choice was available? Please [raise an issue](https://github.com/LaurentRDC/pandoc-plot/issues)!**

## Features

### Captions

You can also specify a caption for your image. This is done using the optional `caption` parameter.

__Markdown__:

~~~markdown
```{.matlabplot caption="This is a simple figure with a **Markdown** caption"}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

figure
plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)
```
~~~

__LaTex__:

```latex
\begin{minted}[caption=This is a simple figure with a caption]{matlabplot}
x  = 0: .1 : 2*pi;
y1 = cos(x);
y2 = sin(x);

figure
plot(x, y1, 'b', x, y2, 'r-.', 'LineWidth', 2)
\end{minted}
```

Caption formatting unfortunately cannot be determined automatically. To specify a caption format (e.g. "markdown", "LaTeX", etc.), see [Configuration](#configuration).

### Link to source code

In case of an output format that supports links (e.g. HTML), the embedded image generated by `pandoc-plot` can show a link to the source code which was used to generate the file. Therefore, other people can see what code was used to create your figures. 

You can turn this on via the `source=true` key:

__Markdown__:

~~~markdown
```{.mathplot source=true}
...
```
~~~

__LaTex__:

```latex
\begin{minted}[source=true]{mathplot}
...
\end{minted}
```

or via a [configuration file](#Configuration).

### Preamble scripts

If you find yourself always repeating some steps, inclusion of scripts is possible using the `preamble` parameter. For example, if you want all Matplotlib plots to have the [`ggplot`](https://matplotlib.org/tutorials/introductory/customizing.html#sphx-glr-tutorials-introductory-customizing-py) style, you can write a very short preamble `style.py` like so:

```python
import matplotlib.pyplot as plt
plt.style.use('ggplot')
```

and include it in your document as follows:

~~~markdown
```{.matplotlib preamble=style.py}
plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')
```
~~~

Which is equivalent to writing the following markdown:

~~~markdown
```{.matplotlib}
import matplotlib.pyplot as plt
plt.style.use('ggplot')

plt.figure()
plt.plot([0,1,2,3,4], [1,2,3,4,5])
plt.title('This is an example figure')
```
~~~

The equivalent LaTeX usage is as follows:

```latex
\begin{minted}[include=style.py]{matplotlib}

\end{minted}
```

This `preamble` parameter is perfect for longer documents with many plots. Simply define the style you want in a separate script! You can also import packages this way, or define functions you often use.

### No wasted work

`pandoc-plot` minimizes work, only generating figures if it absolutely must, i.e. if the content has changed. Therefore, you can confidently run the filter on very large documents containing dozens of figures --- like a book or a thesis --- and only the figures which have changed will be re-generated.

### Compatibility with pandoc-crossref

[`pandoc-crossref`](https://github.com/lierdakil/pandoc-crossref) is a pandoc filter that makes it effortless to cross-reference objects in Markdown documents. 

You can use `pandoc-crossref` in conjunction with `pandoc-plot` for the ultimate figure-making pipeline. You can combine both in a figure like so:

~~~markdown
```{#fig:myexample .plotly_python caption="This is a caption"}
# Insert figure script here
```

As you can see in @fig:myexample, ...
~~~

If the above source is located in file `myfile.md`, you can render the figure and references by applying `pandoc-plot` **first**, and then `pandoc-crossref`. For example:

```bash
pandoc --filter pandoc-plot --filter pandoc-crossref -i myfile.md -o myfile.html
```

## Configuration

To avoid repetition, `pandoc-plot` can be configured using simple YAML files. `pandoc-plot` will look for a `.pandoc-plot.yml` file in the current working directory. Here are **all** the possible parameters:

```yaml
# The following parameters affect all toolkits
directory: plots/
source: false
dpi: 80
format: PNG
caption_format: markdown+tex_math_dollars

# The possible parameters for the Matplotlib toolkit
matplotlib:
  preamble: matplotlib.py
  tight_bbox: false
  transparent: false
  executable: python

# The possible parameters for the MATLAB toolkit
matlabplot:
  preamble: matlab.m
  executable: matlab

# The possible parameters for the Plotly/Python toolkit
plotly_python:
  preamble: plotly-python.py
  executable: python

# The possible parameters for the Mathematica toolkit
mathplot:
  preamble: mathematica.m
  executable: math

# The possible parameters for the GNU Octave toolkit
octaveplot:
  preamble: octave.m
  executable: octave

# The possible parameters for the ggplot2 toolkit
ggplot2:
  preamble: ggplot2.r
  executable: Rscript

# The possible parameters for the gnuplot toolkit
gnuplot:
  preamble: gnuplot.gp
  executable: gnuplot

```

A file like the above sets the **default** values; you can still override them in documents directly.

Using `pandoc-plot --write-example-config` will write the default configuration to a file which you can then customize.

### Executables

The `executable` parameter for all toolkits can be either the executable name (if it is present on the PATH), or the full path to the executable.

Examples:

```yaml
matplotlib:
  executable: python3
```

```yaml
matlabplot:
  executable: "C:\Program Files\Matlab\R2019b\bin\matlab.exe"
```

### Toolkit-specific options

#### Matplotlib

* `tight_bbox` is a boolean that determines whether to use `bbox_inches="tight"` or not when saving Matplotlib figures. For example, `tight_bbox: true`. See [here](https://matplotlib.org/api/_as_gen/matplotlib.pyplot.savefig.html) for details.
* `transparent` is a boolean that determines whether to make Matplotlib figure background transparent or not. This is useful, for example, for displaying a plot on top of a colored background on a web page. High-resolution figures are not affected. For example, `transparent: true`.

## Usage as a Haskell library

To include the functionality of `pandoc-plot` in a Haskell package, you can use the `makePlot` function (for single blocks) or `plotTransform` function (for entire documents). [Take a look at the documentation on Hackage](https://hackage.haskell.org/package/pandoc-plot).

### Usage with Hakyll

In case you want to use the filter with your own Hakyll setup, you can use a transform function that works on entire documents:

```haskell
import Text.Pandoc.Filter.Plot (plotTransform)

import Data.Default (def) -- From data-default package, for default configuration
import Hakyll

-- Unsafe compiler is required because of the interaction
-- in IO (i.e. running an external script).
makePlotPandocCompiler :: Compiler (Item String)
makePlotPandocCompiler = 
  pandocCompilerWithTransformM
    defaultHakyllReaderOptions
    defaultHakyllWriterOptions
    (unsafeCompiler . plotTransform def fmt)
    where
      config = def              -- Default configuration
      fmt    = Just "markdown"  -- Document format, including extensions
```

## Installation

### Binaries and Installers

Windows, Linux, and Mac OS binaries are available on the [GitHub release page](https://github.com/LaurentRDC/pandoc-plot/releases). There are also Windows installers.

### conda

Like `pandoc`, `pandoc-plot` is available as a package installable with [`conda`](https://docs.conda.io/en/latest/). [Click here to see the package page](https://anaconda.org/conda-forge/pandoc-plot).

To install in the current environment:

```sh
conda install -c conda-forge pandoc-plot
```

### From Hackage/Stackage

`pandoc-plot` is available on [Hackage](http://hackage.haskell.org/package/pandoc-plot) and [Stackage](https://www.stackage.org/nightly/package/pandoc-plot). Using the [`cabal-install`](https://www.haskell.org/cabal/) tool:

```bash
cabal update
cabal install pandoc-plot
```

or

```bash
stack update
stack install pandoc-plot
```

### From source

Building from source can be done using [`stack`](https://docs.haskellstack.org/en/stable/README/) or [`cabal`](https://www.haskell.org/cabal/):

```bash
git clone https://github.com/LaurentRDC/pandoc-plot
cd pandoc-plot
stack install # Alternatively, `cabal install`
```

## Warning

Do not run this filter on unknown documents. There is nothing in `pandoc-plot` that can stop a script from performing **evil actions**.