natcap.invest.rst_generator

natcap.invest.rst_generator.describe_input(module_name, keys)

Create RST description for a given model input.

Parameters:

  • module_name (str) – name of the model module

  • keys (list[str]) – series of keys identifying the input

Returns

RST string

natcap.invest.rst_generator.get_input_from_key(module_name, *arg_keys)

Get the Input that corresponds to a given chain of keys

Parameters:

  • module_name (str) – invest model module containing the arg.

  • *arg_keys – one or more strings that are nested arg keys.

Returns:

spec.Input

natcap.invest.rst_generator.invest_spec(name, rawtext, text, lineno, inliner, options={}, content=[])

Custom docutils role to generate InVEST model input docs from spec.

This is a custom Sphinx extension that generates documentation of InVEST model inputs from the model’s MODEL_SPEC. Its purpose is to help us reduce duplicated information and provide consistent, user-friendly documentation. The investspec extension provides the :investspec: role, which can be used inline in RST files to insert generated documentation anywhere you want.

To use in a sphinx project, add ‘natcap.invest.rst_generator’ to the list of extensions in the conf.py.

Usage:

The investspec role takes two arguments: :investspec:module key

module (or f’{investspec_module_prefix}.{module}’ if investspec_module_prefix is defined) must be an importable python module. It must have an attribute MODEL_SPEC .

The second argument specifies which (nested) arg to document. It is a period-separated series of dictionary keys accessed starting at MODEL_SPEC.args. For example:

  • :investspec:annual_water_yield biophysical_table_path

  • :investspec:annual_water_yield biophysical_table_path.columns.kc

Note that this implementation can only generate output that uses standard docutils features, and no sphinx-specific features. See natcap/invest.users-guide#35 for details.

Docutils expects a function that accepts all of these args:

Parameters:

  • name (str) – the local name of the interpreted text role, the role name actually used in the document.

  • rawtext (str) – a string containing the entire interpreted text construct. Return it as a problematic node linked to a system message if there is a problem.

  • text (str) – the interpreted text content, with backslash escapes converted to nulls (\).

  • lineno (int) – the line number where the interpreted text begins.

  • inliner (Inliner) – the Inliner object that called the role function. It defines the following useful attributes: reporter, problematic, memo, parent, document.

  • options (dict) – A dictionary of directive options for customization, to be interpreted by the role function. Used for additional attributes for the generated elements and other functionality.

  • content (list[str]) – the directive content for customization (“role” directive). To be interpreted by the role function.

Interpreted role functions return a tuple of two values:

Returns:

  • A list of nodes which will be inserted into the document tree at

    the point where the interpreted role was encountered

  • A list of system messages, which will be inserted into the

    document tree immediately after the end of the current inline block.

Return type:

a tuple of two values

natcap.invest.rst_generator.parse_rst(text)

Parse RST text into a list of docutils nodes.

Parameters:

text (str) – RST-formatted text to parse. May only use standard docutils features (no Sphinx roles etc)

Returns:

list[docutils.Node]

natcap.invest.rst_generator.setup(app)

Add the custom extension to Sphinx.

Sphinx calls this when it runs conf.py which contains extensions = [‘natcap.invest.investspec’]

Parameters:

app (sphinx.application.Sphinx)

Returns:

empty dictionary