pandoc-pyplot
turns Python code present in your documents to embedded Matplotlib figures.
Usage
The filter recognizes code blocks with the .pyplot
class present. It will run the script in the associated code block in a Python interpreter and capture the generated Matplotlib figure.
Here is a basic example using the scripting matplotlib.pyplot
API:
```{.pyplot}
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:
pandoc --filter pandoc-pyplot input.md --output output.html
or
pandoc --filter pandoc-pyplot input.md --output output.pdf
or any other output format you want.
There are more examples in the source repository, in the \examples
directory.
Features
No wasted work
pandoc-pyplot
minimizes work, only generating figures if it absolutely must. 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 recently changed will be re-generated.
In case of an output format that supports links (e.g. HTML), the embedded image generated by pandoc-pyplot
will be a link to the source code which was used to generate the file. Therefore, other people can see what Python code was used to create your figures. A high resolution image will be made available in a caption link.
Captions
You can also specify a caption for your image. This is done using the optional caption
parameter:
```{.pyplot caption="This is a simple figure"}
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')
```
Caption formatting is either plain text or Markdown. LaTeX-style math is also support in captions (using dollar signs \(...\)).
Including scripts
If you find yourself always repeating some steps, inclusion of scripts is possible using the include
parameter. For example, if you want all plots to have the ggplot
style, you can write a very short preamble style.py
like so:
import matplotlib.pyplot as plt
plt.style.use('ggplot')
and include it in your document as follows:
```{.pyplot include=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:
```{.pyplot}
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')
```
This include
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.
Configurable
New in version 2.1.0.0
To avoid repetition, pandoc-pyplot
can be configured using simple YAML syntax. pandoc-pyplot
will look for a pandoc-pyplot.yml
file in the current working directory:
# You can specify any or all of the following parameters
interpreter: python36
directory: mydirectory/
include: mystyle.py
format: jpeg
dpi: 150
These values override the default values, which are equivalent to:
interpreter: python
directory: generated/
format: png
dpi: 80
Installation
Binaries
Windows binaries are available on GitHub. Place the executable in a location that is in your PATH to be able to call it.
Installers
Windows installers are made available thanks to Inno Setup. You can download them from the release page.
From Hackage/Stackage
pandoc-pyplot
is available on Hackage. Using the cabal-install
tool:
cabal update
cabal install pandoc-pyplot
Similarly, pandoc-pyplot
is available on Stackage:
stack update
stack install pandoc-pyplot
From source
Building from source can be done using stack
or cabal
:
git clone https://github.com/LaurentRDC/pandoc-pyplot
cd pandoc-pylot
stack install # Alternatively, `cabal install`
Running the filter
Requirements
This filter only works with the Matplotlib plotting library. Therefore, you a Python interpreter and at least Matplotlib installed. The name of the Python interpreter to use can be specified in a .pandoc-pyplot.yml
file; by default, pandoc-pyplot
will use the "python"
name.
You can use the filter with Pandoc as follows:
pandoc --filter pandoc-pyplot input.md --output output.html
In which case, the output is HTML. Another example with PDF output:
pandoc --filter pandoc-pyplot input.md --output output.pdf
Python exceptions will be printed to screen in case of a problem.
pandoc-pyplot
has a limited command-line interface. Take a look at the help available using the -h
or --help
argument:
pandoc-pyplot --help
Usage as a Haskell library
To include the functionality of pandoc-pyplot
in a Haskell package, you can use the makePlot :: Block -> IO Block
function (for single blocks) or plotTransform :: Pandoc -> IO Pandoc
function (for entire documents).
Usage with Hakyll
This filter was originally designed to be used 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:
import Text.Pandoc.Filter.Pyplot (plotTransform)
import Hakyll
-- Unsafe compiler is required because of the interaction
-- in IO (i.e. running an external Python script).
makePlotPandocCompiler :: Compiler (Item String)
makePlotPandocCompiler =
pandocCompilerWithTransformM
defaultHakyllReaderOptions
defaultHakyllWriterOptions
(unsafeCompiler . plotTransform)
The plotTransformWithConfig
is also available for a more configurable set-up.
Warning
Do not run this filter on unknown documents. There is nothing in pandoc-pyplot
that can stop a Python script from performing evil actions.