scopesim.reports.rst_utils module

scopesim.reports.rst_utils.latexify_rst_text(rst_text, filename=None, path=None, title_char='=', float_figures=True, use_code_box=True)

Converts an RST string (block of text) into a LaTeX string

NOTE: plots will NOT be generated with this command. For that we must invoke the plotfiy command.

Parameters:

rst_textstr

filenamestr, optional

What to name the latex file. If None, the filename is derived from the text title

pathstr, optional

Where to save the latex file

title_charstr, optional

The character used to underline the rst text title. Usually “=”.

float_figuresbool, optional

Set to False if figures should not be placed by LaTeX. Replaces all egin{figure} with egin{figure}[H]

use_code_boxbool, optional

Adds a box around quote blocks

Returns:

tex_strstr

The same string or block of text in LaTeX format

Examples

::

rst_text = ‘’’ Meaning of life ===============

Apparently it’s 42. Lets plot

This is an included figure caption

‘’’

plotify_rst_text(rst_text) latexify_rst_text(rst_text, filename=”my_latex_file”, path=”./”)

scopesim.reports.rst_utils.plotify_rst_text(rst_text)

Generates and saves plots from code blocks in an RST string

The save directory for the plots defaults to scopesim.rc.__config__["!SIM.reports.image_path"]. This can be overridden ONLY inside a COMMENT block using the path keyword.

Parameters:

rst_textstr

Any RST text string

Notes

• Possible actions are: [reset, clear-figure, plot]

• Code is retained between code blocks in the same string, so we do not need to re-write large sections of code

• By default import numpy as np and import matplotlib.pyplot as plt are loaded automatically, so these do not need to be explicitly specified in each code block.

• THE EXCEPTION is when the action reset is specified. This clears the code_context variable.

Examples

The following rst text will generate a plot and save it in three formats:

..

!! processed by numpydoc !!

scopesim.reports.rst_utils.process_code(context_code, code, options)

Extracts and adds code from the node text to the context_code string

Code can be passed in either a literal_block or comment docutils node. The options regarding what to do with the code are included in either the :class: and :name: tag of a literal_block node, or in a yaml header section in a comment node.

See below for examples of code blocks.

Options for controlling what happens to the code block are as follows:

• name: The filename for the plot

• format: Any matplotlib-accepted file format, e.g: png, pdf, svg, etc.

  Multiple file formats can be

• action: [reset, clear-figure, plot]

  • reset clears the context_code string. By default code is saved from previous code blocks.

  • clear-figure adds plt.clf() to the context string before the current code block is added

  • plot adds plt.savefig({name}.{format}) to the context string. If multiple formats are given, these will be iterated over.

For comment blocks, options should be given in a yaml style header, separated form the code block by exactly three (3) hyphens (’—‘)

For literal_block blocks, we hijack the :class: and :name: attributes. See the examples below. All action keywords are passed to :class:. Format keys are passed as format-<key>.

Parameters:

context_codestr

code from previous Nodes

codestr

code from the current Node

optionsdict

options dictionary derived from Node attributes or RST header blocks

Returns:

context_codestr

Examples

Example of literal_block code block:

.. code::
    :name: my_fug
    :class: reset, clear-figure, plot, format-png

    plt.plot([0,1], [1,1])

.. figure:: my_fug.png
    :name: fig:my_fug

Example of a comment code block:

..
    name: my_fug2
    format: [jpg, svg]
    action: [reset, clear-figure, plot]
    ---
    plt.plot([0,1], [1,0])

.. figure:: my_fug2.jpg
    :name: fig:my_fug2

scopesim.reports.rst_utils.process_comment_code(node, context_code)

Add code from a comment node to the context_code string

scopesim.reports.rst_utils.process_literal_code(node, context_code)

Add code from a literal_block node to the context_code string

scopesim.reports.rst_utils.rstify_rst_text(rst_text, filename=None, path=None, title_char='=')

The same as latexify_rst_text`, but the output is in RST format

scopesim.reports.rst_utils.table_to_rst(tbl, indent=0, rounding=None)

scopesim.reports.rst_utils.walk(node, context_code=None)

Recursively walk through a docutils doctree and run/plot code blocks

Parameters:

nodedocutils.node.Node

context_codestr, optional

A code string inherited from previous code/comment nodes

Returns:

context_codestr

Code to be inherited by subsequent code/comment nodes