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 formated 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 formated 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