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