Run pydocstyle in pre-commit

[michaelosthege]

This runs pydocstyle in the pre-commit and fixes a bunch of things it complained about.

However, I had to silence many errors that were just too common:

id	occurrences	description
D100	62	Missing docstring in public module
D101	62	Missing docstring in public class
D102	568	Missing docstring in public method
D103	98	Missing docstring in public function
D104	10	Missing docstring in public package
D105	47	Missing docstring in magic method
D107	84	Missing docstring in init
D200	23	One-line docstring should fit on one line with quotes
D202	59	No blank lines allowed after function docstring
D203	254	1 blank line required before class docstring
D204	47	1 blank line required after class docstring
D205	155	1 blank line required between summary line and description
D209	16	Multi-line docstring closing quotes should be on a separate line
D212	231	Multi-line docstring summary should start at the first line
D213	330	Multi-line docstring summary should start at the second line
D301	30	Use r""" if any backslashes in a docstring
D400	349	First line should end with a period
D401	98	First line should be in imperative mood
D403	14	First word of the first line should be properly capitalized
D413	341	Missing blank line after last section
D415	334	First line should end with a period, question mark, or exclamation point
D417	089	Missing argument descriptions in the docstring

Closes #6378

Checklist

• Explain important implementation details 👆
• Make sure that the pre-commit linting/style checks pass.
• Link relevant issues (preferably in nice commit messages)
• Are the changes covered by tests and docstrings?
• Fill out the short summary sections 👇

Major / Breaking Changes

• None

Bugfixes / New features

• None

Docs / Maintenance

• Now running pydocstyle in the pre-commit
• Fixed several docstring formatting issues.

[codecov]

Codecov Report

Merging #6382 (944b85d) into main (adf6fff) will decrease coverage by 58.19%.
The diff coverage is 100.00%.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #6382       +/-   ##
===========================================
- Coverage   94.79%   36.60%   -58.20%     
===========================================
  Files         148      148               
  Lines       27488    27488               
===========================================
- Hits        26058    10061    -15997     
- Misses       1430    17427    +15997     

Impacted Files	Coverage Δ
pymc/blocking.py	95.55% <ø> (ø)
pymc/distributions/continuous.py	58.16% <ø> (-39.52%)	⬇️
pymc/distributions/discrete.py	55.52% <ø> (-43.71%)	⬇️
pymc/distributions/dist_math.py	42.85% <ø> (-44.58%)	⬇️
pymc/distributions/distribution.py	68.57% <ø> (-28.89%)	⬇️
pymc/distributions/multivariate.py	46.19% <ø> (-46.09%)	⬇️
pymc/distributions/transforms.py	51.26% <ø> (-48.11%)	⬇️
pymc/distributions/truncated.py	34.50% <ø> (-64.79%)	⬇️
pymc/gp/util.py	36.78% <ø> (-59.78%)	⬇️
pymc/logprob/abstract.py	81.70% <ø> (-15.86%)	⬇️
... and 133 more

[ricardoV94]

Except for the D100s... it seems like we should have the others enabled and they shouldn't be too hard to fix no?

[michaelosthege]

Except for the D100s... it seems like we should have the others enabled and they shouldn't be too hard to fix no?

Some of them are in conflict with black and have no effect on the output (D202,D203,D204). Those we can keep ignoring.

We should enable the others, but that will be one beginner friendly PR per number.
I'm not going to fix several hundred lines by hand on this branch.

[OriolAbril]

The convention arg is missing, we should be using numpy as convention (which should remove the contradictory warnings happening all at the same time)

[OriolAbril]

e.g. D212 and D213 make no sense together.

[michaelosthege]

Just tried it, but with --convention one can't pass --ignore and then we'd have hundreds of errors and would need to fix them all in one go (unrealistic..)

[OriolAbril]

let's keep ignore then

jumped the gun too fast

[OriolAbril]

I have also just realised we have https://github.com/pymc-devs/pymc/blob/main/setup.cfg#L7 which seems to be ignored for some reason? maybe we ought to install pydocstyle[toml]?