-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A Pandoc filter to include figures generated from Python code blocks -- -- A Pandoc filter to include figures generated from Python code blocks. -- Keep the document and Python code in the same location. Output is -- captured and included as a figure. @package pandoc-pyplot @version 2.3.0.1 -- | This module re-exports internal pandoc-pyplot functionality. module Text.Pandoc.Filter.Pyplot.Internal -- | 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. configuration :: FilePath -> IO Configuration -- | Write a configuration to file. An exception will be raised in case the -- file would be overwritten. writeConfig :: FilePath -> Configuration -> IO () -- | list of all keys related to pandoc-pyplot that can be specified in -- source material. inclusionKeys :: [Text] -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. directoryKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. captionKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. dpiKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. includePathKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. saveFormatKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. withLinksKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. isTightBboxKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. isTransparentKey :: Text -- | Datatype containing all parameters required to run pandoc-pyplot. -- -- It is assumed that once a FigureSpec has been created, no -- configuration can overload it; hence, a FigureSpec completely -- encodes a particular figure. data FigureSpec FigureSpec :: Text -> Bool -> PythonScript -> SaveFormat -> FilePath -> Int -> RenderingLibrary -> Bool -> Bool -> Attr -> FigureSpec -- | Figure caption. [caption] :: FigureSpec -> Text -- | Append links to source code and high-dpi figure to caption. [withLinks] :: FigureSpec -> Bool -- | Source code for the figure. [script] :: FigureSpec -> PythonScript -- | Save format of the figure. [saveFormat] :: FigureSpec -> SaveFormat -- | Directory where to save the file. [directory] :: FigureSpec -> FilePath -- | Dots-per-inch of figure. [dpi] :: FigureSpec -> Int -- | Rendering library. [renderingLib] :: FigureSpec -> RenderingLibrary -- | Enforce tight bounding-box with bbox_inches="tight". [tightBbox] :: FigureSpec -> Bool -- | Make figure background transparent. [transparent] :: FigureSpec -> Bool -- | Attributes not related to pandoc-pyplot will be propagated. [blockAttrs] :: FigureSpec -> Attr -- | Generated figure file format supported by pandoc-pyplot. Note: all -- formats are supported by Matplotlib, but not all formats are supported -- by Plotly data SaveFormat PNG :: SaveFormat PDF :: SaveFormat SVG :: SaveFormat JPG :: SaveFormat EPS :: SaveFormat GIF :: SaveFormat TIF :: SaveFormat -- | Convert a FigureSpec to a Pandoc block component. Note that -- the script to generate figure files must still be run in another -- function. toImage :: FigureSpec -> Block -- | Determine the path to the source code that generated the figure. sourceCodePath :: FigureSpec -> FilePath -- | Determine the path a figure should have. figurePath :: FigureSpec -> FilePath -- | Modify a Python plotting script to save the figure to a filename. An -- additional file will also be captured. addPlotCapture :: FigureSpec -> PythonScript -- | Determine inclusion specifications from Block attributes. -- Note that the ".pyplot" OR .plotly class is -- required, but all other parameters are optional. parseFigureSpec :: Block -> PyplotM (Maybe FigureSpec) -- | Save format file extension extension :: SaveFormat -> String -- | Take a python script in string form, write it in a temporary -- directory, then execute it. runTempPythonScript :: PythonScript -> PyplotM ScriptResult -- | Run the Python script. In case the file already exists, we can safely -- assume there is no need to re-run it. runScriptIfNecessary :: FigureSpec -> PyplotM ScriptResult -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. directoryKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. captionKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. dpiKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. includePathKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. saveFormatKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. withLinksKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. isTightBboxKey :: Text -- | Keys that pandoc-pyplot will look for in code blocks. These are only -- exported for testing purposes. isTransparentKey :: Text -- | list of all keys related to pandoc-pyplot that can be specified in -- source material. inclusionKeys :: [Text] -- | Monad in which to run pandoc-pyplot computations type PyplotM a = ReaderT Configuration IO a -- | String representation of a Python script type PythonScript = Text -- | Rendering library data RenderingLibrary -- | Rendering via the Matplotlib library. This library has the most -- features. Matplotlib :: RenderingLibrary -- | Rendering via the Plotly library. Plotly :: RenderingLibrary -- | Possible result of running a Python script data ScriptResult ScriptSuccess :: ScriptResult ScriptChecksFailed :: String -> ScriptResult ScriptFailure :: Int -> ScriptResult -- | Result of checking scripts for problems data CheckResult CheckPassed :: CheckResult CheckFailed :: String -> CheckResult -- | Possible errors returned by the filter data PandocPyplotError -- | Running Python script has yielded an error ScriptError :: Int -> PandocPyplotError -- | Python script did not pass all checks ScriptChecksFailedError :: String -> PandocPyplotError -- | Generated figure file format supported by pandoc-pyplot. Note: all -- formats are supported by Matplotlib, but not all formats are supported -- by Plotly data SaveFormat PNG :: SaveFormat PDF :: SaveFormat SVG :: SaveFormat JPG :: SaveFormat EPS :: SaveFormat GIF :: SaveFormat TIF :: SaveFormat -- | Save format file extension extension :: SaveFormat -> String -- | Default interpreter should be Python 3, which has a different name on -- Windows ("python") vs Unix ("python3") defaultPlatformInterpreter :: String -- | 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 data Configuration Configuration :: FilePath -> PythonScript -> Bool -> SaveFormat -> Int -> Bool -> Bool -> String -> [String] -> Configuration -- | The default directory where figures will be saved. [defaultDirectory] :: Configuration -> FilePath -- | The default script to run before other instructions. [defaultIncludeScript] :: Configuration -> PythonScript -- | The default behavior of whether or not to include links to source code -- and high-res [defaultWithLinks] :: Configuration -> Bool -- | The default save format of generated figures. [defaultSaveFormat] :: Configuration -> SaveFormat -- | The default dots-per-inch value for generated figures. Matplotlib -- only, ignored otherwise. [defaultDPI] :: Configuration -> Int -- | Whether the figures should be saved with bbox_inches="tight" -- or not. Useful for larger figures with subplots. Matplotlib only, -- ignored otherwise. [isTightBbox] :: Configuration -> Bool -- | If True, figures will be saved with transparent background rather than -- solid color. .Matplotlib only, ignored otherwise. [isTransparent] :: Configuration -> Bool -- | The name of the interpreter to use to render figures. [interpreter] :: Configuration -> String -- | Command-line flags to be passed to the Python interpreger, e.g. ["-O", -- "-Wignore"] [flags] :: Configuration -> [String] -- | Datatype containing all parameters required to run pandoc-pyplot. -- -- It is assumed that once a FigureSpec has been created, no -- configuration can overload it; hence, a FigureSpec completely -- encodes a particular figure. data FigureSpec FigureSpec :: Text -> Bool -> PythonScript -> SaveFormat -> FilePath -> Int -> RenderingLibrary -> Bool -> Bool -> Attr -> FigureSpec -- | Figure caption. [caption] :: FigureSpec -> Text -- | Append links to source code and high-dpi figure to caption. [withLinks] :: FigureSpec -> Bool -- | Source code for the figure. [script] :: FigureSpec -> PythonScript -- | Save format of the figure. [saveFormat] :: FigureSpec -> SaveFormat -- | Directory where to save the file. [directory] :: FigureSpec -> FilePath -- | Dots-per-inch of figure. [dpi] :: FigureSpec -> Int -- | Rendering library. [renderingLib] :: FigureSpec -> RenderingLibrary -- | Enforce tight bounding-box with bbox_inches="tight". [tightBbox] :: FigureSpec -> Bool -- | Make figure background transparent. [transparent] :: FigureSpec -> Bool -- | Attributes not related to pandoc-pyplot will be propagated. [blockAttrs] :: FigureSpec -> Attr -- | 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: -- -- -- -- Here are the possible attributes what pandoc-pyplot understands: -- -- -- -- Custom configurations are possible via the Configuration type -- and the filter functions plotTransformWithConfig and -- makePlotWithConfig. module Text.Pandoc.Filter.Pyplot -- | Highest-level function that can be walked over a Pandoc tree. All code -- blocks that have the .pyplot / .plotly class will be -- considered figures. makePlot :: Block -> IO Block -- | like makePlot with with a custom default values. makePlotWithConfig :: Configuration -> Block -> IO Block -- | Walk over an entire Pandoc document, changing appropriate code blocks -- into figures. Default configuration is used. plotTransform :: Pandoc -> IO Pandoc -- | Walk over an entire Pandoc document, changing appropriate code blocks -- into figures. The default values are determined by a -- Configuration. plotTransformWithConfig :: Configuration -> Pandoc -> IO Pandoc -- | 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. configuration :: FilePath -> IO 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 data Configuration Configuration :: FilePath -> PythonScript -> Bool -> SaveFormat -> Int -> Bool -> Bool -> String -> [String] -> Configuration -- | The default directory where figures will be saved. [defaultDirectory] :: Configuration -> FilePath -- | The default script to run before other instructions. [defaultIncludeScript] :: Configuration -> PythonScript -- | The default behavior of whether or not to include links to source code -- and high-res [defaultWithLinks] :: Configuration -> Bool -- | The default save format of generated figures. [defaultSaveFormat] :: Configuration -> SaveFormat -- | The default dots-per-inch value for generated figures. Matplotlib -- only, ignored otherwise. [defaultDPI] :: Configuration -> Int -- | Whether the figures should be saved with bbox_inches="tight" -- or not. Useful for larger figures with subplots. Matplotlib only, -- ignored otherwise. [isTightBbox] :: Configuration -> Bool -- | If True, figures will be saved with transparent background rather than -- solid color. .Matplotlib only, ignored otherwise. [isTransparent] :: Configuration -> Bool -- | The name of the interpreter to use to render figures. [interpreter] :: Configuration -> String -- | Command-line flags to be passed to the Python interpreger, e.g. ["-O", -- "-Wignore"] [flags] :: Configuration -> [String] -- | String representation of a Python script type PythonScript = Text -- | Generated figure file format supported by pandoc-pyplot. Note: all -- formats are supported by Matplotlib, but not all formats are supported -- by Plotly data SaveFormat PNG :: SaveFormat PDF :: SaveFormat SVG :: SaveFormat JPG :: SaveFormat EPS :: SaveFormat GIF :: SaveFormat TIF :: SaveFormat -- | Possible errors returned by the filter data PandocPyplotError -- | Running Python script has yielded an error ScriptError :: Int -> PandocPyplotError -- | Python script did not pass all checks ScriptChecksFailedError :: String -> PandocPyplotError -- | Main routine to include plots. Code blocks containing the attributes -- .pyplot or .plotly are considered Python plotting -- scripts. All other possible blocks are ignored. makePlot' :: Block -> PyplotM (Either PandocPyplotError Block)