Docstrings & parameter name

xfel_calibrate/calibrate.py

@@ -351,7 +351,18 @@ def make_extended_parser() -> argparse.ArgumentParser:
     add_args_from_nb(nb, parser, cvar=cvar)
     return parser
 
-def add_args_from_nb(nb, parser, cvar=None, overwrite_reqs=False):
+def add_args_from_nb(nb, parser, cvar=None, no_required=False):
+    """Add argparse arguments for parameters in the first cell of a notebook.
+
+    Uses nbparameterise to extract the parameter information. Each foo_bar
+    parameter gets a --foo-bar command line option.
+    Boolean parameters get a pair of flags like --abc and --no-abc.
+
+    :param nb: NotebookNode object representing a loaded .ipynb file
+    :param parser: argparse.ArgumentParser instance
+    :param str cvar: Name of the concurrency parameter.
+    :param bool no_required: If True, none of the added options are required.
+    """
     parser.description = make_epilog(nb)
     parms = extract_parameters(nb)
 
@@ -361,7 +372,7 @@ def add_args_from_nb(nb, parser, cvar=None, overwrite_reqs=False):
                    else "{}. Default: %(default)s".format(p.comment.replace("#", " ").strip()))
         required = (p.comment is not None
                     and "required" in p.comment
-                    and not overwrite_reqs
+                    and not no_required
                     and p.name != cvar)
 
         # This may be not a public API
@@ -402,7 +413,7 @@ def add_args_from_nb(nb, parser, cvar=None, overwrite_reqs=False):
                                     type=p.type,
                                     default=default,
                                     help=helpstr,
-                                required=required)
+                                    required=required)
 
 def extend_params(nb, extend_func_name):
     """Add parameters in the first code cell by calling a function in the notebook
@@ -418,7 +429,7 @@ def extend_params(nb, extend_func_name):
 
     # Make a temporary parser that won't exit if it sees -h or --help
     pre_parser = make_initial_parser(add_help=False)
-    add_args_from_nb(nb, pre_parser, overwrite_reqs=True)
+    add_args_from_nb(nb, pre_parser, no_required=True)
     known, _ = pre_parser.parse_known_args()
     args = deconsolize_args(vars(known))
 
@@ -475,7 +486,7 @@ def flatten_list(l):
 def set_figure_format(nb, enable_vector_format):
     """Set svg format in inline backend for figures
 
-    If parameter 'vector_figs' is set to True svg format will
+    If parameter enable_vector_format is set to True, svg format will
     be used for figures in the notebook rendering. Subsequently  vector
     graphics figures will be used for report.
     """