Discussed here: https://github.com/DanielNoord/pydocstringformatter/issues/169

Things to iron out:

• [ ] should arguments be added to enable it? (--num-passes ... --no-check ????) .... I vote no arguments ...
• [x] should the error be more user-friendly?
• [ ] Regarding the failing tests ... option A. Fix the formatters so they become compatible, option B. Fix the tests so the incompatible formatters do not get called together (also change the defauts of just adding the --style"numpydoc" to prevent automatic collisions ...). LMK what you think.
• [x] testing ... Right not by "playing with it" it works but a better unit testing is required.

https://github.com/DanielNoord/pydocstringformatter/issues/169#issuecomment-1249090803

I haven't looked at your branch as I am on mobile, but I'm highly in favour of this change. I'll gladly help review a PR but sadly won't have time to work on this myself this week.

Some pointers to consider:

* I think the maximum run count should be 2.

* After the second run, a third run should occur. If we still create changes (note that these should ignore the --write flag but should only check if there are any potential change) we need to emit an error. `black` has a very elegant system where after there is an inconsistency aftwr 2/3 runs a pre-regenerated bug report is send to stdout. This can then be copied to an issue in GitHub which would allow us to resolve the issue.

* We should test the issue template. So we need to write two incompatible test formatters and write a test where they fail to find a solution.

That's all I can think of for now. Let me know if you have any questions! 😊

• [ ] Issue template to report the problems

Current error:

>           raise RuntimeError(msg)
E           RuntimeError: Conflicting formatters: numpydoc-section-spacing, closing-quotes
E           --- numpydoc-section-spacing vs closing-quotes /private/var/folders/5j/x2qvf77j1m7736lccs2xt6c40000gn/T/pytest-of-sebastianpaez/pytest-187/test_formatting_numpydoc_numpy0/test_file.py
E           +++ numpydoc-section-spacing vs closing-quotes /private/var/folders/5j/x2qvf77j1m7736lccs2xt6c40000gn/T/pytest-of-sebastianpaez/pytest-187/test_formatting_numpydoc_numpy0/test_file.py
E           @@ -1,2 +1 @@
E           -"""A docstring.
E           -    """
E           +"""A docstring."""

Improved the toml parsing so it supports BooleanOptionalAction arguments in it. (also added tests for it ...)

[tool.pydocstringformatter]
write = false
style = ["numpydoc"]
strip-whitespaces = true  # <<<<<- previously unsupported
split-summary-body = false # <<<<<- previously unsupported
no-numpydoc-section-hyphen-length = true # <<<<<- previously unsupported

.... where should I document this?

pip install pydocstringformatter gives the following error

ERROR: Could not find a version that satisfies the requirement pydocstringformatter (from versions: none) ERROR: No matching distribution found for pydocstringformatter

Am I missing something?

Related to #125; I got the bits I could think how to automate for the docstring style I actually use (numpydoc)

Should probably extend the tests for more types of docstrings and more sections within each docstring.

Ideally the section test would have docstrings on

• [X] function
• [ ] class
• [ ] method
• [x] generator
• [x] module
• [x] constant

and would test the ordering of some subset of these sections:

• [X] Parameters
• [X] Returns
• [X] Raises
• [ ] Examples
• [x] Yields
• [x] References

Formatters for:

• [X] name-colon parameter spacing (x : float not x:float or x: float)
• [X] Section ordering
• [x] Section spacing (blank line between sections)
• [x] Length of line of hyphens after section header (should be same length as section header)

TODO List:

• [x] Create branch with changes in PR and branch with merge-base (see mypy)
• [x] Run pydocstringformatter with merge-base branch in write mode
• [x] Checkout to changes branch
• [x] Do a non-write branch to get diff
• [x] Prettify diff
• [x] Probably tons more...

Here's my proposed solution. It should work in all cases, as it will default to the system default, if the file has different line endings (file.newlines returns a tuple).

I manually tested it with Unix, Dos, and Mac formatted files, and they all retained their line endings.

Fixes #115.

Partially handles #7, it's not even close right now 😄 The line wrapping fail because there are space before and after the leading string.

• [ ] Line wrapping after certain line length
• [ ] make line length configurable, search for settings of other tools (black, pylint)
• [ ] Break up multiple sentences on first line into summary and main block (see PEP 256)
• [ ] Handle numpy/google style docstrings gracefully with line wrapping

Hey Daniel, The emoji in the last print statement under run.py crashes when using Python version that does not support emojis.

UnicodeEncodeError: 'charmap' codec can't encode character '\U0001f389' in position 42: character maps to <undefined>

For example for my Python 3.5.3, Windows 10 Pro 64 bit.

Do we want to support older version of Python with this tool? If so maybe the print statement should be modified?

Bumps pytest from 7.1.3 to 7.2.0.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

added pyc and pycache to gitignore

(I would personally add venv as well, since it is a very common practice to have the virtual environment in the same directory as the project)

Work in progress, this still need more robust tests. This would permit to automatically generate the arguments and to activate or deactivate every parser while still having a default.

Updates the requirements on sphinx to permit the latest version.

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

I ran pydocstringformatter --max-line-length=10 -w example.py on the command line, expecting pydocstringformatter will change this:

"""Hello yeeeeeeeee."""

to this:

"""Hello yeee
   eeeeee."""

But I didn't see any change. Did I do anything wrong with the command line?

In the following example pydocstringformatter add a .\n after "that".

def _looks_like_subscriptable(node: ClassDef) -> bool:
    """
    Returns True if the node corresponds to a ClassDef of the Collections.abc module that
    supports subscripting
    """
    pass

It would be nice to detect summary better, see https://github.com/PyCQA/astroid/pull/1792#issuecomment-1250256197

Hi again ...

So I wanted to pitch improving the example/doctest (https://docs.python.org/3/library/doctest.html) support in the library.

Right now the behavior is pretty ... not great.

This ....

def my_function(lst):
    """
    >>> my_function([1,  1,
    ...     1,2,3,3,4, 5])
    "processed [1,1,1,2,3,3,4,5]"
    """

    return "processed " + str(lst)

Becomes ....

def my_function(lst):
    """
    >>> my_function([1,  1,.

    ...     1,2,3,3,4, 5])
    "processed [1,1,1,2,3,3,4,5]"
    """

    return "processed " + str(lst)

I am proposing ...

• [ ] adding support for this type of expressions
• [ ] if possible 'blackening' the code
• [ ] in the case of numpydocs, make sure it is inside an Examples section (https://numpydoc.readthedocs.io/en/v1.4.0/format.html#examples)

Ideal output for reference:

def my_function(lst):
    """
    >>> my_function([1,1,1,2,3,3,4,5])
    "processed [1,1,1,2,3,3,4,5]"
    """

    return "processed " + str(lst)

I think it would be great to have better docs in a couple of instances.

1. Examples of the supported documentation styles
2. Examples of the changes implied by the configuration arguments.
3. Improve the description of the arguments that shows up with --help to make clear what styles it applies to.
4. Make clear what it entails to change the --style argument or have several, whether it is going to convert the docstrings to that style (example??). And when having multiple styles, whether the expectation should be that it will allow sections that have each style or can each individual docstring have only one?

I think it should be done in a way that it is auto-generated or tested. We could even add some of the formatting tests to the documentation. This would entail some changes in the making/rendering of the documentation.

LMK what you think, I think that if we agree on what the correct approach will be I will be happy to help adding those. Best!