Text.Pandoc.Filter.Pyplot

This module defines a Pandoc filter makePlot that can be used to walk over a Pandoc document and generate figures from Python code blocks.

The syntax for code blocks is simple, Code blocks with the .pyplot attribute will trigger the filter. The code block will be reworked into a Python script and the output figure will be captured, along with a high-resolution version of the figure and the source code used to generate the figure.

To trigger pandoc-pyplot, the following is required:

• .pyplot: Trigger pandoc-pyplot but let it decide on a filename

Here are the possible attributes what pandoc-pyplot understands:

• target=...: Filepath where the resulting figure should be saved.
• directory=... : Directory where to save the figure.
• caption="...": Specify a plot caption (or alternate text).
• dpi=...: Specify a value for figure resolution, or dots-per-inch. Default is 80DPI.
• include=...: Path to a Python script to include before the code block. Ideal to avoid repetition over many figures.

Here are some example blocks in Markdown:

This is a paragraph

```{.pyplot caption="This is a caption."}
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')
```

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)

Documentation

makePlot :: Block -> IO Block

Highest-level function that can be walked over a Pandoc tree. All code blocks that have the '.pyplot' parameter will be considered figures.

plotTransform :: Pandoc -> IO Pandoc

Walk over an entire Pandoc document, changing appropriate code blocks into figures.

data PandocPyplotError

Possible errors returned by the filter

Constructors

ScriptError Int

Running Python script has yielded an error

BlockingCallError

Python script contains a block call to 'show()'

Instances

Eq PandocPyplotError

Defined in Text.Pandoc.Filter.Pyplot

Methods

(==) :: PandocPyplotError -> PandocPyplotError -> Bool

(/=) :: PandocPyplotError -> PandocPyplotError -> Bool

Show PandocPyplotError

Defined in Text.Pandoc.Filter.Pyplot

Methods

showsPrec :: Int -> PandocPyplotError -> ShowS

show :: PandocPyplotError -> String

showList :: [PandocPyplotError] -> ShowS

makePlot' :: Block -> IO (Either PandocPyplotError Block)

Main routine to include Matplotlib plots. Code blocks containing the attributes .pyplot are considered Python plotting scripts. All other possible blocks are ignored.

directoryKey :: String

Keys that pandoc-pyplot will look for in code blocks. These are only exported for testing purposes.

captionKey :: String

Keys that pandoc-pyplot will look for in code blocks. These are only exported for testing purposes.

dpiKey :: String

Keys that pandoc-pyplot will look for in code blocks. These are only exported for testing purposes.

includePathKey :: String

Keys that pandoc-pyplot will look for in code blocks. These are only exported for testing purposes.

saveFormatKey :: String

Keys that pandoc-pyplot will look for in code blocks. These are only exported for testing purposes.