Skip to content

[WIP] PR: formatting of generated docstrings according to style-guides #24041

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

[WIP] PR: formatting of generated docstrings according to style-guides #24041

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9eba1f4
Format generated docstring according to style guides
rhkarls Mar 25, 2025
a6671b8
Exclude return section if callable return only None
rhkarls Mar 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 40 additions & 30 deletions spyder/plugins/editor/extensions/docstring.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,7 @@ def _generate_numpy_doc(self, func_info):
indent1 = func_info.func_indent + self.code_editor.indent_chars
indent2 = func_info.func_indent + self.code_editor.indent_chars * 2

numpy_doc += '\n{}\n'.format(indent1)
numpy_doc += '\n{}SUMMARY.\n'.format(indent1)

if len(arg_names) > 0:
numpy_doc += '\n{}Parameters'.format(indent1)
Expand Down Expand Up @@ -435,14 +435,6 @@ def _generate_numpy_doc(self, func_info):

numpy_doc += arg_text

if func_info.raise_list:
numpy_doc += '\n{}Raises'.format(indent1)
numpy_doc += '\n{}------'.format(indent1)
for raise_type in func_info.raise_list:
numpy_doc += '\n{}{}'.format(indent1, raise_type)
numpy_doc += '\n{}DESCRIPTION.'.format(indent2)
numpy_doc += '\n'

numpy_doc += '\n'
if func_info.has_yield:
header = '{0}Yields\n{0}------\n'.format(indent1)
Expand All @@ -458,19 +450,32 @@ def _generate_numpy_doc(self, func_info):
return_element_type = indent1 + '{return_type}\n' + indent2 + \
'DESCRIPTION.'
placeholder = return_element_type.format(return_type='TYPE')
return_element_name = indent1 + '{return_name} : ' + \
placeholder.lstrip()
if len([rv for rvs in func_info.return_value_in_body for rv in rvs.split(",")]) == 1:
# numpydoc RT02, only include type and not name if it's a single return value
return_element_name = indent1 + placeholder.lstrip()
else:
return_element_name = indent1 + '{return_name} : ' + \
placeholder.lstrip()

try:
return_section = self._generate_docstring_return_section(
func_info.return_value_in_body, header,
return_element_name, return_element_type, placeholder,
indent1)
except (ValueError, IndexError):
return_section = '{}{}None.'.format(header, indent1)
return_section = ''

numpy_doc += return_section
numpy_doc += '\n\n{}{}'.format(indent1, self.quote3)

if func_info.raise_list:
numpy_doc += '\n\n{}Raises'.format(indent1)
numpy_doc += '\n{}------'.format(indent1)
for raise_type in func_info.raise_list:
numpy_doc += '\n{}{}'.format(indent1, raise_type)
numpy_doc += '\n{}DESCRIPTION.'.format(indent2)

numpy_doc = numpy_doc.rstrip('\n')
numpy_doc += '\n{}{}'.format(indent1, self.quote3)

return numpy_doc

Expand All @@ -490,7 +495,7 @@ def _generate_google_doc(self, func_info):
indent1 = func_info.func_indent + self.code_editor.indent_chars
indent2 = func_info.func_indent + self.code_editor.indent_chars * 2

google_doc += '\n{}\n'.format(indent1)
google_doc += 'SUMMARY.\n'

if len(arg_names) > 0:
google_doc += '\n{0}Args:\n'.format(indent1)
Expand All @@ -514,18 +519,11 @@ def _generate_google_doc(self, func_info):

if arg_value:
arg_value = arg_value.replace(self.quote3, self.quote3_other)
arg_text += ' Defaults to {}.\n'.format(arg_value)
else:
arg_text += '\n'
arg_text += ' Defaults to {}.'.format(arg_value)

google_doc += arg_text
arg_text += '\n'

if func_info.raise_list:
google_doc += '\n{0}Raises:'.format(indent1)
for raise_type in func_info.raise_list:
google_doc += '\n{}{}'.format(indent2, raise_type)
google_doc += ': DESCRIPTION.'
google_doc += '\n'
google_doc += arg_text

google_doc += '\n'
if func_info.has_yield:
Expand All @@ -549,10 +547,18 @@ def _generate_google_doc(self, func_info):
return_element_name, return_element_type, placeholder,
indent2)
except (ValueError, IndexError):
return_section = '{}{}None.'.format(header, indent2)
return_section = ''

google_doc += return_section
google_doc += '\n\n{}{}'.format(indent1, self.quote3)

if func_info.raise_list:
google_doc += '\n\n{0}Raises:'.format(indent1)
for raise_type in func_info.raise_list:
google_doc += '\n{}{}'.format(indent2, raise_type)
google_doc += ': DESCRIPTION.'

google_doc = google_doc.rstrip('\n')
google_doc += '\n{}{}'.format(indent1, self.quote3)

return google_doc

Expand All @@ -571,7 +577,7 @@ def _generate_sphinx_doc(self, func_info):

indent1 = func_info.func_indent + self.code_editor.indent_chars

sphinx_doc += '\n{}\n'.format(indent1)
sphinx_doc += 'SUMMARY.\n\n'

arg_text = ''
for arg_name, arg_type, arg_value in zip(arg_names, arg_types,
Expand Down Expand Up @@ -608,7 +614,9 @@ def _generate_sphinx_doc(self, func_info):
header = '{}:return:'.format(indent1)

return_type_annotated = func_info.return_type_annotated
if return_type_annotated:
if not func_info.return_value_in_body and not return_type_annotated:
return_section = ''
elif return_type_annotated:
return_section = '{} DESCRIPTION\n'.format(header)
return_section += '{}:rtype: {}'.format(indent1,
return_type_annotated)
Expand All @@ -617,7 +625,9 @@ def _generate_sphinx_doc(self, func_info):
return_section += '{}:rtype: TYPE'.format(indent1)

sphinx_doc += return_section
sphinx_doc += '\n\n{}{}'.format(indent1, self.quote3)

sphinx_doc = sphinx_doc.rstrip('\n')
sphinx_doc += '\n{}{}'.format(indent1, self.quote3)

return sphinx_doc

Expand Down Expand Up @@ -723,7 +733,7 @@ def _generate_docstring_return_section(self, return_vals, header,
non_none_vals = [return_val for return_val in return_vals
if return_val and return_val != 'None']
if not non_none_vals:
return header + indent + 'None.'
return ''

# Get only values with matching brackets that can be cleaned up
non_none_vals = [return_val.strip(' ()\t\n').rstrip(',')
Expand Down
Loading