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

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.