Skip to content
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.

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

NumpydocSectionSpacingFormatter collides with ClosingQuotesFormatter #177

Closed
jspaezp opened this issue Sep 20, 2022 · 1 comment · Fixed by #181
Closed

NumpydocSectionSpacingFormatter collides with ClosingQuotesFormatter #177

jspaezp opened this issue Sep 20, 2022 · 1 comment · Fixed by #181

Comments

@jspaezp
Copy link
Contributor

jspaezp commented Sep 20, 2022

It was discussed: #173
(check the whole conversation if you want more context)

  1. NumpydocSectionSpacingFormatter collides with ClosingQuotesFormatter
    Feature: two-pass formatting of the tokens #173 (comment)

Looking at the conflicting formatters ....

NumpydocSectionSpacingFormatter collides with ClosingQuotesFormatter

NumpydocSectionSpacingFormatter https://github.com/jspaezp/pydocstringformatter/blob/858c1dabe6880e7367f692674bdc731eae398fe1/pydocstringformatter/_formatting/formatters_numpydoc.py#L104 generates:

'"""\n    A docstring\n    """'

ClosingQuotesFormatter https://github.com/jspaezp/pydocstringformatter/blob/858c1dabe6880e7367f692674bdc731eae398fe1/pydocstringformatter/_formatting/formatters_default.py#L119 generates:

'"""A docstring"""'

Looking at references

Numpydoc differentiates between short summary and extended summary. https://numpydoc.readthedocs.io/en/latest/format.html#short-summary

where I think the correct out would be ...

# CURRENT
'"""\n    A docstring\n    """'

# Expected
'"""A docstring\n\n    """'

Which for sure would be incompatible....

* Solution 1: Make `NumpydocSectionSpacingFormatter` not modify anything if there is only one section.

* Solution 2: Make `NumpydocSectionSpacingFormatter` by making it call the `ClosingQuotesFormatter` on its current output.

* Solution 2: Add a Formatter.conflcting atttribute (also entails fixing the tests so that one of the args is disabled)
  
  * Op1: and check for conflicting formatters when calling _Run, warn about the behavior and disable all conflciting formatters.
  * Op2: same but error out instead of warning (also entails changing the defaults)

Extras:

1. Improve documentation for closing-quotes to make the behavior more explicit.
  --beginning-quotes, --no-beginning-quotes
                        Activate or deactivate beginning-quotes: Fix the position of the opening quotes. Styles: default. (default: True)
  --closing-quotes, --no-closing-quotes
                        Activate or deactivate closing-quotes: Fix the position of the closing quotes. Styles: default. (default: True)
@DanielNoord
Copy link
Owner

Like I said in #173 (comment).

I think the expected is:

# Expected
'"""A docstring"""'

Numpy refers to PEP256 in their introduction as well. If the docstring doesn't include any of the Numpy flavour we should default to the rules as defined by PEP256 which includes that one-line docstrings should be on one line.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants