validate_docstrings.py as a separate package?

[rth]

The docstring validation script is quite nice! I would like to use it for instance to validate docsting in scikit-learn, e.g.

python pandas/scripts/validate_docstrings.py sklearn.linear_model.LinearRegression

works, but then is a bit more difficult to customize being pandas specific.
In particular it would be nice to have the ability to specify which error to include / exclude in some config file. Also for instance scikit-learn has some default configuration for doctests that is currently ignored in setup.cfg,

[tool:pytest]
doctest_optionflags = NORMALIZE_WHITESPACE ELLIPSIS

Overall, it would be nice if this script was a separate project with a shared core functionality and possibly some config that that projects could personalize a bit if needed (although going with the 'black' approach with one set of rules for all is also a possibility).

Docstring validation is a problem that is relevant for a number of scientific python projects and it would be a shame if each one solves it independently. As far as I can tell, so far this script provides more relevant errors for scientific python projects that say pydocstyle. Using the same tool for validation, would also help making docstrings formatting more consistent across projects.

Also this script is bound to grow in scope (e.g. #28701) and eventually sharing the maintenance with maintainers of other projects might be useful. Although I agree that it might add some overhead with respect to your CI integration.

[WillAyd]

Thanks - this was discussed in #27342 and something we would generally agree with. @datapythonista did you ever get traction with numpydoc on that discussion?

[rth]

Great! I think there was mostly positive feedback in numpy/numpydoc#213 . They are waiting for a PR :)

[brandondavid]

xref numpy/numpydoc#238

[datapythonista]

So far adding the validation function for a docstring to numpydoc in numpy/numpydoc#238

The function is only available via python, but I think the next step could be make python -m numpydoc sklearn.linear_model.LinearRegression validate that docstring reporting errors based on settings in setup.cfg.

But for the CI, may be it's work implement a Python script in each project that calls the validation? I guess we want to fetch the objects to validate in Python. May be we can create an issue in numpydoc to discuss what makes sense. We don't necessarily need to agree on everything, but worth knowing what each project wants to do, to have in numpydoc all or most of the code that we want to reuse from project to project.

[WillAyd]

Closed by numpy/numpydoc#238 and now part of numpy doc - thanks @datapythonista