macrostat.util.latex_model_documentation#

Utility functions for extracting and formatting docstring information from Behavior classes.

Functions

convert_docstring_to_latex(docstring[, label])

Convert a docstring to LaTeX text and align equations.

create_latex_content(behavior_class[, ...])

Generate LaTeX content for a model's documentation.

extract_equations_from_docstring(docstring)

Extract the Equations section from a docstring and format it for LaTeX.

find_called_methods(method_node)

Extract the names of methods called within a method's AST node.

generate_latex_documentation(behavior_class)

Make a LaTeX model description from a Behavior class.

parse_behavior_docstrings(behavior_class)

Extract docstrings from methods called by initialize() or step() that have an Equations section.
macrostat.util.latex_model_documentation.convert_docstring_to_latex(docstring: str, label: str = None) → str[source]#

Convert a docstring to LaTeX text and align equations.

This function is used to convert a docstring to LaTeX text and add the equations to the docstring in an align environment.

Parameters:

  • docstring (str) – The docstring to convert to LaTeX.

  • label (str, optional) – The label of the equation. If None, no label is added.

Returns:

The LaTeX text and align equations.

Return type:

str

macrostat.util.latex_model_documentation.create_latex_content(behavior_class: Type[Behavior], title: str = None, subsec: bool = True, preamble: str = None) → str[source]#

Generate LaTeX content for a model’s documentation.

This function creates a complete LaTeX document structure for documenting a model’s behavior class. It starts with a preamble and title, then adds a section for the initialization of the model, including any methods called by initialize(). It then adds a section for the step() method, including any methods called by step().

Parameters:

  • behavior_class (Type[Behavior]) – The Behavior class to document

  • title (str, optional) – Optional title for the document. If None, uses the class name

  • subsec (bool, optional) – If True, creates a subsection instead of a section

  • preamble (str, optional) – Optional LaTeX preamble to include before the document content

Returns:

Complete LaTeX document as a string

Return type:

str

macrostat.util.latex_model_documentation.extract_equations_from_docstring(docstring: str) → str[source]#

Extract the Equations section from a docstring and format it for LaTeX.

This function is used to extract the Equations section from a docstring and format it for LaTeX. It eliminates any sphinx directives and other text that is not part of the equations, and, if it finds an align environment, it removes the outermost align environment.

Parameters:

docstring (str) – The docstring containing an Equations section.

Returns:

The formatted LaTeX equations.

Return type:

str

macrostat.util.latex_model_documentation.find_called_methods(method_node: FunctionDef) → Set[str][source]#

Extract the names of methods called within a method’s AST node.

This function is used to extract the names of the methods called within a method’s AST node. It is used to determine which methods are called by the initialize() and step() methods of a Behavior class.

Parameters:

method_node (ast.FunctionDef) – The AST node of the method.

Returns:

Set of method names called within the method.

Return type:

Set[str]

macrostat.util.latex_model_documentation.generate_latex_documentation(behavior_class: Type[Behavior], output_file: str = None, title: str = None, subsec: bool = True, preamble: str = None) → str[source]#

Make a LaTeX model description from a Behavior class.

This function takes a Behavior class and returns a LaTeX model description by parsing the docstrings of the initialize() and the step() methods. It then copies the docstrings of those methods and all of the methods that they call. From each, it extracts the description and the equations section, and then formats them for LaTeX. It then saves the LaTeX code to a file if an output file is provided.

Parameters:

  • behavior_class (Type[Behavior]) – The Behavior class to make a LaTeX model description from.

  • output_file (str, optional) – The file to save the LaTeX model description to.

  • title (str, optional) – The title of the LaTeX model description.

  • subsec (bool, optional) – If True, add a subsection for each method. If False, just append the description and equations.

  • preamble (str, optional) – A string of LaTeX code to add to the preamble of the document, i.e. before the begin{document} command.

Returns:

The LaTeX model description.

Return type:

str

Examples

>>> from macrostat.models import get_model
>>> GL06SIM = get_model("GL06SIM")
>>> tex = generate_documentation(GL06SIM().behavior)
>>> print(tex)
macrostat.util.latex_model_documentation.parse_behavior_docstrings(behavior_class: Type[Behavior]) → Dict[str, Dict[str, str]][source]#

Extract docstrings from methods called by initialize() or step() that have an Equations section.

This function is used to extract the docstrings of the methods called by the initialize() and step() methods of a Behavior class. It then returns a dictionary with two keys: ‘initialize’ and ‘step’, each containing a dictionary mapping method names to their docstrings.

Parameters:

behavior_class (Type[Behavior]) – The Behavior class to extract docstrings from.

Returns:

Dictionary with two keys: ‘initialize’ and ‘step’, each containing a dictionary mapping method names to their docstrings.

Return type:

Dict[str, Dict[str, str]]