Add pydocstringformatter

[akaszynski]

In an effort to universally fix wrapping for our docstrings, I came across pydocstringformatter. It has the potential to be that solution in the future, but for the time being it's fairly limited.

I still find it quite useful at preventing simple mistakes that would normally take forever to show up in the normal documentation build. Since it does basic enforcement of numpydoc standards, let's include this.

I'm on the fence of if we should include or not include this in the blame.

[codecov]

Codecov Report

Merging #4125 (a1b0123) into main (d7f6b79) will decrease coverage by 5.29%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #4125      +/-   ##
==========================================
- Coverage   95.56%   90.28%   -5.29%     
==========================================
  Files          95       95              
  Lines       20247    20247              
==========================================
- Hits        19350    18279    -1071     
- Misses        897     1968    +1071     

[adeak]

I'm on the fence of if we should include or not include this in the blame.

Not if we add changes to the pre-commit hooks here 😛

As far as the docs changes go, I'm also on the fence. On the one hand +61/-41 diff means this isn't significant at all, so we can just keep the diff. It's also slightly weird to see the first line of docstrings be broken up, because I thought that this was the basis of the blurb rendered on the page listing methods for a class. But apparently that doesn't seem to be the case:

("Plotter.scalar_bar - First scalar bar", missing the part about backwards compat.)

[akaszynski]

Not if we add changes to the pre-commit hooks here

Then we must include it. Thanks.

It's also slightly weird to see the first line of docstrings be broken up

PEP257 recommends:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line...

Where a one-line docstring:

The docstring is a phrase ending in a period.

So, one phrase on one line. Turns out we're not aligned. We just need to provide a good "first phrase" and enforce that through CI.

[adeak]

Not if we add changes to the pre-commit hooks here

Then we must include it. Thanks.

I managed to write the opposite of what I meant, so thanks for figuring it out anyway.