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