Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New Doc Style Guide #85

Merged
merged 14 commits into from
May 18, 2022
Merged

New Doc Style Guide #85

merged 14 commits into from
May 18, 2022

Conversation

jorgepiloto
Copy link
Member

Partially solves for #64.

@jorgepiloto jorgepiloto force-pushed the feat/doc_style branch 3 times, most recently from 159fd79 to 21fe385 Compare May 4, 2022 06:58
@jorgepiloto
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Member Author

jorgepiloto commented May 4, 2022

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
Copy link
Member Author

jorgepiloto commented May 4, 2022

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
Copy link
Member Author

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

@jorgepiloto
Copy link
Member Author

Opening pyvista/numpydoc-validation#2.

@jorgepiloto
Copy link
Member Author

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 jorgepiloto force-pushed the feat/doc_style branch 2 times, most recently from 542f989 to 8532376 Compare May 4, 2022 16:40
@jorgepiloto
Copy link
Member Author

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
Copy link
Member Author

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.

@jorgepiloto jorgepiloto marked this pull request as ready for review May 16, 2022 07:33
jorgepiloto and others added 2 commits May 16, 2022 10:00
Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com>
@jorgepiloto jorgepiloto requested review from PipKat and MaxJPRey May 16, 2022 16:18
@MaxJPRey
Copy link
Contributor

MaxJPRey commented May 17, 2022

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

@jorgepiloto
Copy link
Member Author

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

Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com>
@jorgepiloto jorgepiloto merged commit e5d3c62 into main May 18, 2022
@jorgepiloto jorgepiloto deleted the feat/doc_style branch May 18, 2022 08:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants