nipype.utils.docparse module

Utilities to pull in documentation from command-line tools.

Examples

# Instantiate bet object from nipype.interfaces import fsl from nipype.utils import docparse better = fsl.Bet() docstring = docparse.get_doc(better.cmd, better.opt_map)

nipype.utils.docparse.build_doc(doc, opts)

Build docstring from doc and options

Parameters:

• rep_doc (string) – Documentation string

• opts (dict) – Dictionary of option attributes and keys. Use reverse_opt_map to reverse flags and attrs from opt_map class attribute.

Returns:

newdoc – The docstring with flags replaced with attribute names and formatted to match nipy standards (as best we can).

Return type:

string

nipype.utils.docparse.format_params(paramlist, otherlist=None)

Format the parameters according to the nipy style conventions.

Since the external programs do not conform to any conventions, the resulting docstrings are not ideal. But at a minimum the Parameters section is reasonably close.

Parameters:

• paramlist (list) – List of strings where each list item matches exactly one parameter and it’s description. These items will go into the ‘Parameters’ section of the docstring.

• otherlist (list) – List of strings, similar to paramlist above. These items will go into the ‘Other Parameters’ section of the docstring.

Returns:

doc – The formatted docstring.

Return type:

string

nipype.utils.docparse.get_doc(cmd, opt_map, help_flag=None, trap_error=True)

Get the docstring from our command and options map.

Parameters:

• cmd (string) – The command whose documentation we are fetching

• opt_map (dict) – Dictionary of flags and option attributes.

• help_flag (string) – Provide additional help flag. e.g., -h

• trap_error (boolean) – Override if underlying command returns a non-zero returncode

Returns:

doc – The formatted docstring

Return type:

string

nipype.utils.docparse.get_params_from_doc(cmd, style='--', help_flag=None, trap_error=True)

Auto-generate option map from command line help

Parameters:

• cmd (string) – The command whose documentation we are fetching

• style (string default [’–‘]) – The help command style (–, -). Multiple styles can be provided in a list e.g. [’–‘,’-‘].

• help_flag (string) – Provide additional help flag. e.g., -h

• trap_error (boolean) – Override if underlying command returns a non-zero returncode

Returns:

optmap – Contains a mapping from input to command line variables

Return type:

dict

nipype.utils.docparse.grab_doc(cmd, trap_error=True)

Run cmd without args and grab documentation.

Parameters:

• cmd (string) – Command line string

• trap_error (boolean) – Ensure that returncode is 0

Returns:

doc – The command line documentation

Return type:

string

nipype.utils.docparse.insert_doc(doc, new_items)

Insert new_items into the beginning of the doc

Docstrings in new_items will be inserted right after the Parameters header but before the existing docs.

Parameters:

• doc (str) – The existing docstring we’re inserting docmentation into.

• new_items (list) – List of strings to be inserted in the doc.

Examples

>>> from nipype.utils.docparse import insert_doc
>>> doc = '''Parameters
... ----------
... outline :
...     something about an outline'''

>>> new_items = ['infile : str', '    The name of the input file']
>>> new_items.extend(['outfile : str', '    The name of the output file'])
>>> newdoc = insert_doc(doc, new_items)
>>> print(newdoc)

Parameters:

• infile (str) – The name of the input file

• outfile (str) – The name of the output file

• outline – something about an outline

nipype.utils.docparse.replace_opts(rep_doc, opts)

Replace flags with parameter names.

This is a simple operation where we replace the command line flags with the attribute names.

Parameters:

• rep_doc (string) – Documentation string

• opts (dict) – Dictionary of option attributes and keys. Use reverse_opt_map to reverse flags and attrs from opt_map class attribute.

Returns:

rep_doc – New docstring with flags replaces with attribute names.

Return type:

string

Examples

doc = grab_doc(‘bet’) opts = reverse_opt_map(fsl.Bet.opt_map) rep_doc = replace_opts(doc, opts)

nipype.utils.docparse.reverse_opt_map(opt_map)

Reverse the key/value pairs of the option map in the interface classes.

Parameters:

opt_map (dict) – Dictionary mapping the attribute name to a command line flag. Each interface class defines these for the command it wraps.

Returns:

rev_opt_map – Dictionary mapping the flags to the attribute name.

Return type:

dict