From 320dcabe1aa1b1093a0f8a117a0df8ca009ade9c Mon Sep 17 00:00:00 2001 From: Felix von Drigalski Date: Thu, 12 May 2022 09:43:59 +0900 Subject: [PATCH 1/2] Add comment --- pyment/docstring.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyment/docstring.py b/pyment/docstring.py index 338f130..50eb58f 100644 --- a/pyment/docstring.py +++ b/pyment/docstring.py @@ -1984,7 +1984,7 @@ def _set_raw_params(self, sep): raw += '\n' elif self.dst.style['out'] == 'groups': pass - else: + else: # sphinx/reST style with_space = lambda s: '\n'.join( [self.docs['out']['spaces'] + l if i > 0 else l for i, l in enumerate(s.splitlines())] ) From 92db4d6f7ef8b33aa00e72fb615e615b22fbb5ed Mon Sep 17 00:00:00 2001 From: Felix von Drigalski Date: Thu, 12 May 2022 09:42:53 +0900 Subject: [PATCH 2/2] Throw more helpful error if docstring malformed --- pyment/docstring.py | 120 ++++++++++++++++++++++++-------------------- 1 file changed, 65 insertions(+), 55 deletions(-) diff --git a/pyment/docstring.py b/pyment/docstring.py index 50eb58f..538bd2b 100644 --- a/pyment/docstring.py +++ b/pyment/docstring.py @@ -973,68 +973,78 @@ def _extra_tagstyle_elements(self, data): style_return = self.opt['return'][self.style['in']]['name'][:-1] style_raise = self.opt['raise'][self.style['in']]['name'][:-1] last_element = {'nature': None, 'name': None} - for line in data.splitlines(): + for idx, line in enumerate(data.splitlines()): param_name = None param_type = None param_description = None param_part = None # parameter statement - if line.strip().startswith(style_param): - last_element['nature'] = 'param' - last_element['name'] = None - line = line.strip().replace(style_param, '', 1).strip() - if ':' in line: - param_part, param_description = line.split(':', 1) - else: - print("WARNING: malformed docstring parameter") - res = re.split(r'\s+', param_part.strip()) - if len(res) == 1: - param_name = res[0].strip() - elif len(res) == 2: - param_type, param_name = res[0].strip(), res[1].strip() - else: - print("WARNING: malformed docstring parameter") - if param_name: - # keep track in case of multiline + try: + if line.strip().startswith(style_param): last_element['nature'] = 'param' - last_element['name'] = param_name - if param_name not in ret: - ret[param_name] = {'type': None, 'type_in_param': None, 'description': None} - if param_type: - ret[param_name]['type_in_param'] = param_type - if param_description: - ret[param_name]['description'] = param_description.strip() - else: - print("WARNING: malformed docstring parameter: unable to extract name") - # type statement - elif line.strip().startswith(style_type): - last_element['nature'] = 'type' - last_element['name'] = None - line = line.strip().replace(style_type, '', 1).strip() - if ':' in line: - param_name, param_type = line.split(':', 1) - param_name = param_name.strip() - param_type = param_type.strip() - else: - print("WARNING: malformed docstring parameter") - if param_name: - # keep track in case of multiline + last_element['name'] = None + line = line.strip().replace(style_param, '', 1).strip() + if ':' in line: + param_part, param_description = line.split(':', 1) + else: + print("WARNING: malformed docstring parameter") + res = re.split(r'\s+', param_part.strip()) + if len(res) == 1: + param_name = res[0].strip() + elif len(res) == 2: + param_type, param_name = res[0].strip(), res[1].strip() + else: + print("WARNING: malformed docstring parameter") + if param_name: + # keep track in case of multiline + last_element['nature'] = 'param' + last_element['name'] = param_name + if param_name not in ret: + ret[param_name] = {'type': None, 'type_in_param': None, 'description': None} + if param_type: + ret[param_name]['type_in_param'] = param_type + if param_description: + ret[param_name]['description'] = param_description.strip() + else: + print("WARNING: malformed docstring parameter: unable to extract name") + # type statement + elif line.strip().startswith(style_type): last_element['nature'] = 'type' - last_element['name'] = param_name - if param_name not in ret: - ret[param_name] = {'type': None, 'type_in_param': None, 'description': None} - if param_type: - ret[param_name]['type'] = param_type.strip() - elif line.strip().startswith(style_raise) or line.startswith(style_return): - # fixme not managed in this function - last_element['nature'] = 'raise-return' - last_element['name'] = None - else: - # suppose to be line of a multiline element - if last_element['nature'] == 'param': - ret[last_element['name']]['description'] += f"\n{line}" - elif last_element['nature'] == 'type': - ret[last_element['name']]['description'] += f"\n{line}" + last_element['name'] = None + line = line.strip().replace(style_type, '', 1).strip() + if ':' in line: + param_name, param_type = line.split(':', 1) + param_name = param_name.strip() + param_type = param_type.strip() + else: + print("WARNING: malformed docstring parameter") + if param_name: + # keep track in case of multiline + last_element['nature'] = 'type' + last_element['name'] = param_name + if param_name not in ret: + ret[param_name] = {'type': None, 'type_in_param': None, 'description': None} + if param_type: + ret[param_name]['type'] = param_type.strip() + elif line.strip().startswith(style_raise) or line.startswith(style_return): + # fixme not managed in this function + last_element['nature'] = 'raise-return' + last_element['name'] = None + else: + if line is None: + print("line was None and cast to string.") + # suppose to be line of a multiline element + if last_element['nature'] == 'param': + ret[last_element['name']]['description'] += f"\n{line}" + elif last_element['nature'] == 'type': + ret[last_element['name']]['description'] += f"\n{line}" + except Exception as e: + print("Something went wrong: ", e) + print("In this docstring:", data) + print("") + print("Problem was caused by line number " + str(idx) + ":", line) + print("Is it formatted correctly? Check for missing colons. Missing lines are not supported.") + raise e return ret def _extract_not_tagstyle_old_way(self, data):