Skip to content

DOC: Add validation error when a docstring is missing #23648

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

Closed
datapythonista opened this issue Nov 12, 2018 · 1 comment · Fixed by #23673
Closed

DOC: Add validation error when a docstring is missing #23648

datapythonista opened this issue Nov 12, 2018 · 1 comment · Fixed by #23673
Labels
CI Continuous Integration Docs good first issue
Milestone

Comments

@datapythonista
Copy link
Member

We have the script scripts/validate_docstrings.py that checks several formatting errors in the docstrings.

Currently, when a function, method... has no docstring at all, it fails few of the checks, but we don't have one specific to it. See for example:

$ ./scripts/validate_docstrings.py --prefix=pandas.Series.imag
pandas.Series.imag: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
pandas.Series.imag: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
pandas.Series.imag: No summary found (a short summary in a single line should be present at the beginning of the docstring)

What would be useful is to add a new check, that reports that the function does not have a docstring. And in the previous errors, check when the docstring is empty, and do not report them. So the previous call should report a single error with a text like pandas.Series.imag: No docstring found.

@avolkov
Copy link
Contributor

avolkov commented Nov 12, 2018

I'm working on Pandas at PyconCa sprint I'll give it a go.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment