New Doc Style Guide

[jorgepiloto]

Partially solves for #64.

[jorgepiloto]

I'm investigating how "pydocstyle" and "numpydoc_validation_checks" fit together. It does not have the sense to have two cheks that aim for the same goal. However, I am not sure about the capabilities and robustness of each one.

[jorgepiloto]

Of course, they are compatible. The numpydoc extension is limited to checking docstring compliance according to numpy convention whereas pydocstyle aims to check for PEP 257 guides.

Nevertheless, I made some tests locally for checking the robustness of numpydoc by imposing numpydoc_validation_checks = {"all"} and some intentional errors were not caught by this extension.

[jorgepiloto]

Alright, if python -m numpydoc --validate import_path is executed, `numpy_validation" errors are properly caught. Why Sphinx is not getting those even after enabling the "numpydoc" extension...?

[jorgepiloto]

Unless some .. autodirective is used to document a function, class or module, Sphinx will not check for the source files, meaning that numpy_validation_chekcs are not executed!

[jorgepiloto]

Hahaha, it looks like @akaszynski already faced this issue, opened numpy/numpydoc#364, and devised numpydoc-validation.

[jorgepiloto]

Opening pyvista/numpydoc-validation#2.

[jorgepiloto]

I'm reviewing this in deep, especially the configuration for the various cited tools. I want to make sure they are not in conflict or that we are imposing double conditions at the same time.

[jorgepiloto]

Once PyCQA/docformatter#77 gets merged and a new release is published, it will be possible to update docformatter configuration to a pyproject.toml one.

[jorgepiloto]

This is ready for review, @PipKat @MaxJPRey and @Revathyvenugopal162. I moved the "Class Documentation" section to the "Guidelines and Best Practices". This chapter is expected to be renamed "How-To" in an incoming PR.

[MaxJPRey]

@jorgepiloto Excellent work. Thanks!
Thanks @PipKat for the the thorough review.

[jorgepiloto]

GitHub didn't allowed me to apply suggested changes in "batch mode", not sure why... I manually applied those.