Fix documentation build main

[beroda]

This is an (another and hopefully last) attempt to resolve #3782

[codecov]

Codecov Report

Merging #3799 (47fe743) into main (bda7d71) will increase coverage by 0.02%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##             main    #3799      +/-   ##
==========================================
+ Coverage   94.15%   94.18%   +0.02%     
==========================================
  Files          86       86              
  Lines       18891    18899       +8     
==========================================
+ Hits        17787    17800      +13     
+ Misses       1104     1099       -5     

[MatthewFlamm]

We should merge #3800, if it works, first. This will allow us to check that this PR indeed fixes the issue.

[beroda]

@MatthewFlamm Thank you !

[beroda]

I think the should finish with a period warning at the end of a parameter's description (as reported here) should be captured by pydocstyle and not by the full documentation build (which is performed very rarely by devs).

But unfortunately I was not able to find any error code associated with that http://www.pydocstyle.org/en/stable/error_codes.html 😢

[banesullivan]

Recommend merging to fix the build on main.

We can figure out how to handle those warnings with pydicstyle later

[MatthewFlamm]

LGTM

[MatthewFlamm]

I think the should finish with a period warning at the end of a parameter's description (as reported here) should be captured by pydocstyle and not by the full documentation build (which is performed very rarely by devs).

But unfortunately I was not able to find any error code associated with that http://www.pydocstyle.org/en/stable/error_codes.html 😢

I believe pydocstyle is mostly checker for pep 257, which is much less prescriptive than numpydoc. In fact, pep 257 has examples with parameter descriptions that do not end in a period. See https://peps.python.org/pep-0257/.

For numpydoc, we could try https://numpydoc.readthedocs.io/en/latest/validation.html#docstring-validation-using-python.

Edit: Annoyingly, to use this, you have to specify every single function that you want to check. You cannot specify a package or module. Running python -m numpydoc pyvista.Cell.copy_meta_from using current main branch does yield an error for {'**kwargs', '*args'}, but it also returns error for things we have ignored for the documentation check in conf.py. This seems like something that is better requested to be part of numpydoc.

More edits: It looks like the numpydoc validation originated from Pandas. Pandas maintains a script for scraping public api function docstrings here and then customizing numpydoc validation: https://github.com/pandas-dev/pandas/blob/main/scripts/validate_docstrings.py. Instead of re-implementing here, it would be preferable if again, Pandas merged the public api portion of the code into numpydoc.