armi.utils.dochelpers module

Helpers for sphinx documentation.

Can be used by armi docs or docs of anything else that can import armi.

armi.utils.dochelpers.create_figure(path, caption=None, align=None, alt=None, width=None)

This method is available within .. exec::. It allows someone to create a figure with a caption.

armi.utils.dochelpers.create_table(rst_table, caption=None, align=None, widths=None, width=None)

This method is available within .. exec::. It allows someone to create a table with a caption.

The rst_table

armi.utils.dochelpers.createListTable(rows, caption=None, align=None, widths=None, width=None, klass=None)

Take a list of data, and produce an RST-type string for a list-table.

Parameters:

• rows (list) – List of input data (first row is the header).

• align (str) – “left”, “center”, or “right”

• widths (str) – “auto”, “grid”, or a list of integers

• width (str) – length or percentage of the line, surrounded by backticks

• klass (str) – Should be “class”, but that is a reserved keyword. “longtable”, “special”, or something custom

Returns:

str

Return type:

RST list-table string

class armi.utils.dochelpers.ExecDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Execute the specified python code and insert the output into the document.

The code is used as the body of a method, and must return a str. The string result is interpreted as reStructuredText.

Error handling informed by https://docutils.sourceforge.io/docs/howto/rst-directives.html#error-handling The self.error function should both inform the documentation builder of the error and also insert an error into the built documentation.

Warning

This only works on a single node in the doctree, so the rendered code may not contain any new section names or labels. They will result in WARNING: Unexpected section title warnings.

has_content = True

May the directive have content?

run()

class armi.utils.dochelpers.PyReverse(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Runs pyreverse to generate UML for specified module name and options.

The directive accepts the same arguments as pyreverse, except you should not specify --project or -o (output format). These are automatically specified.

If you pass -c to this, the figure generated is forced to be the className.png like BurnMatrix.png. For .gitignore purposes, this is a pain. Thus, we auto-prefix ALL images generated by this directive with pyrev_.

has_content = True

May the directive have content?

required_arguments = 1

Number of required directive arguments.

optional_arguments = 50

Number of optional arguments after the required arguments.

option_spec = {'align': <function PyReverse.<lambda>>, 'alt': <function unchanged>, 'filename': <function unchanged>, 'height': <function length_or_percentage_or_unitless>, 'width': <function length_or_percentage_or_unitless>}

Mapping of option names to validator functions.

run()

armi.utils.dochelpers.generateParamTable(klass, fwParams, app=None)

Return a string containing one or more restructured text list tables containing parameter descriptions for the passed ArmiObject class.

Parameters:

• klass (ArmiObject subclass) – The Class for which parameter tables should be generated

• fwParams (ParameterDefinitionCollection) – A parameter definition collection containing the parameters that are always defined for the passed klass. The rest of the parameters come from the plugins registered with the passed app

• app (App, optional) – The ARMI-based application to draw plugins from.

Notes

It would be nice to have better section labels between the different sources but this cannot be done withing an exec directive in Sphinx so we settle for just putting in anchors for hyperlinking to.

armi.utils.dochelpers.generatePluginSettingsTable(settings, pluginName)

Return a string containing one or more restructured text list tables containing settings descriptions for a plugin.

Parameters:

settings (list of Settings) – This is a list of settings definitions, typically returned by a defineSettings plugin hook.