Text.Pandoc.Filter.Pyplot

This module defines a Pandoc filter makePlot and related functions 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 or .plotly 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, one of the following is required:

• .pyplot: Trigger pandoc-pyplot, rendering via the Matplotlib library
• .plotly: Trigger pandoc-pyplot, rendering via the Plotly library

Here are the possible attributes what pandoc-pyplot understands:

• directory=... : Directory where to save the figure.
• format=...: Format of the generated figure. This can be an extension or an acronym, e.g. format=png.
• caption="...": Specify a plot caption (or alternate text). Captions support Markdown formatting and LaTeX math ($...$).
• dpi=...: Specify a value for figure resolution, or dots-per-inch. Default is 80DPI. (Matplotlib only, ignored otherwise)
• include=...: Path to a Python script to include before the code block. Ideal to avoid repetition over many figures.
• links=true|false: Add links to source code and high-resolution version of this figure. This is true by default, but you may wish to disable this for PDF output.

Custom configurations are possible via the Configuration type and the filter functions plotTransformWithConfig and makePlotWithConfig.

Operating on single Pandoc blocks

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.

makePlotWithConfig :: Configuration -> Block -> IO Block

like makePlot with with a custom default values.

Since: 2.1.0.0

Operating on whole Pandoc documents

plotTransform :: Pandoc -> IO Pandoc

Walk over an entire Pandoc document, changing appropriate code blocks into figures. Default configuration is used.

plotTransformWithConfig :: Configuration -> Pandoc -> IO Pandoc

Walk over an entire Pandoc document, changing appropriate code blocks into figures. The default values are determined by a Configuration.

Since: 2.1.0.0

For configuration purposes

configuration :: FilePath -> IO Configuration

Building configuration from a YAML file. The keys are exactly the same as for Markdown code blocks.

If a key is either not present or unreadable, its value will be set to the default value.

Since: 2.1.0.0

data Configuration

Configuration of pandoc-pyplot, describing the default behavior of the filter.

A Configuration is useful when dealing with lots of figures; it avoids repeating the same values.sta

Since: 2.1.0.0

Constructors

Configuration

Fields

• defaultDirectory :: FilePath

  The default directory where figures will be saved.

• defaultIncludeScript :: PythonScript

  The default script to run before other instructions.

• defaultWithLinks :: Bool

  The default behavior of whether or not to include links to source code and high-res

• defaultSaveFormat :: SaveFormat

  The default save format of generated figures.

• defaultDPI :: Int

  The default dots-per-inch value for generated figures. Matplotlib only, ignored otherwise.

• isTightBbox :: Bool

  Whether the figures should be saved with bbox_inches="tight" or not. Useful for larger figures with subplots. Matplotlib only, ignored otherwise.

• isTransparent :: Bool

  If True, figures will be saved with transparent background rather than solid color. .Matplotlib only, ignored otherwise.

• interpreter :: String

  The name of the interpreter to use to render figures.

• flags :: [String]

  Command-line flags to be passed to the Python interpreger, e.g. ["-O", "-Wignore"]

Instances

Eq Configuration

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

(==) :: Configuration -> Configuration -> Bool

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

Show Configuration

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

showsPrec :: Int -> Configuration -> ShowS

show :: Configuration -> String

showList :: [Configuration] -> ShowS

ToJSON Configuration

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

toJSON :: Configuration -> Value

toEncoding :: Configuration -> Encoding

toJSONList :: [Configuration] -> Value

toEncodingList :: [Configuration] -> Encoding

Default Configuration

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

def :: Configuration

type PythonScript = Text

String representation of a Python script

data SaveFormat

Generated figure file format supported by pandoc-pyplot. Note: all formats are supported by Matplotlib, but not all formats are supported by Plotly

Constructors

PNG

PDF

SVG

JPG

EPS

GIF

TIF

Instances

Bounded SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

minBound :: SaveFormat

maxBound :: SaveFormat

Enum SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

succ :: SaveFormat -> SaveFormat

pred :: SaveFormat -> SaveFormat

toEnum :: Int -> SaveFormat

fromEnum :: SaveFormat -> Int

enumFrom :: SaveFormat -> [SaveFormat]

enumFromThen :: SaveFormat -> SaveFormat -> [SaveFormat]

enumFromTo :: SaveFormat -> SaveFormat -> [SaveFormat]

enumFromThenTo :: SaveFormat -> SaveFormat -> SaveFormat -> [SaveFormat]

Eq SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

(==) :: SaveFormat -> SaveFormat -> Bool

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

Show SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

showsPrec :: Int -> SaveFormat -> ShowS

show :: SaveFormat -> String

showList :: [SaveFormat] -> ShowS

Generic SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Associated Types

type Rep SaveFormat :: Type -> Type

Methods

from :: SaveFormat -> Rep SaveFormat x

to :: Rep SaveFormat x -> SaveFormat

Hashable SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

hashWithSalt :: Int -> SaveFormat -> Int

hash :: SaveFormat -> Int

type Rep SaveFormat

Defined in Text.Pandoc.Filter.Pyplot.Types

type Rep SaveFormat = D1 (MetaData "SaveFormat" "Text.Pandoc.Filter.Pyplot.Types" "pandoc-pyplot-2.2.0.0-BU3m2WTXS6j2pUZ0YTPViA" False) ((C1 (MetaCons "PNG" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "PDF" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "SVG" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "JPG" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "EPS" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "GIF" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "TIF" PrefixI False) (U1 :: Type -> Type))))

For testing and internal purposes only

data PandocPyplotError

Possible errors returned by the filter

Constructors

ScriptError Int

Running Python script has yielded an error

ScriptChecksFailedError String

Python script did not pass all checks

Instances

Eq PandocPyplotError

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

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

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

Show PandocPyplotError

Defined in Text.Pandoc.Filter.Pyplot.Types

Methods

showsPrec :: Int -> PandocPyplotError -> ShowS

show :: PandocPyplotError -> String

showList :: [PandocPyplotError] -> ShowS

makePlot' :: Block -> PyplotM (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.