Home · Quickstart · User Guide and Examples · Interfaces Index · Developers · About · Nipy

# 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