macrostat.util.autodocs#
Utility functions for extracting and formatting docstring information from Behavior classes.
Functions
|
Convert a docstring to LaTeX text and align equations. |
|
Convert a docstring to the rst markdown syntax. |
|
Generate LaTeX content for a model's documentation. |
|
Generate rst content for a model's documentation. |
|
Extract the Equations section from a docstring and format it for LaTeX. |
|
Extract the names of methods called within a method's AST node. |
|
Convert a docstring into a dict of sections and their content. |
|
Make a model description from a Behavior class. |
|
Extract docstrings from methods called by initialize() or step() that have an Equations section. |
- macrostat.util.autodocs.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.
- macrostat.util.autodocs.convert_docstring_to_rst(docstring: str, label: str = None) str[source]#
Convert a docstring to the rst markdown syntax.
- macrostat.util.autodocs.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:
- macrostat.util.autodocs.create_rst_content(behavior_class: Type[Behavior], title: str = None, subsec: bool = False) str[source]#
Generate rst content for a model’s documentation. Primarily for docs.
This function creates a complete rst 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 rst document as a string
- Return type:
- macrostat.util.autodocs.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.
- macrostat.util.autodocs.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.autodocs.gather_docstring_sections(docstring: str) dict[source]#
Convert a docstring into a dict of sections and their content. The first section is called Description
- macrostat.util.autodocs.generate_docs(behavior_class: Type[Behavior], output_file: str = None, docstyle: str = 'latex', title: str = None, subsec: bool = True, preamble: str = None) str[source]#
Make a model description from a Behavior class.
This function takes a Behavior class and returns a 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. It then saves the docs to a file if an output file is provided.
- Parameters:
behavior_class (Type[Behavior]) – The Behavior class to make a model description from.
output_file (str, optional) – The file to save the model description to.
docstyle (str, default "latex") – The type of documentation to make
title (str, optional) – The title of the 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. Only for LaTeX
- Returns:
The model description.
- Return type:
Examples
>>> from macrostat.models import get_model >>> GL06SIM = get_model("GL06SIM") >>> tex = generate_docs(GL06SIM().behavior, dostyle="latex") >>> print(tex)
- macrostat.util.autodocs.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.