Closed
Description
Problem description
I am currently working on my PR for documentation sprint (for pd.DataFrame.to_csv
)) and have a few issues with the docsting validation script, please see below. Master merged ~5 minutes ago, so everything should be up to date.
"Code"
My "Parameters" section starts with:
Parameters
----------
path_or_buf : str or file handle, default None
File path or object, if None is provided the result is returned as
a string.
sep : str (length 1), default ','
Field delimiter for the output file.
na_rep : str, default ''
Missing data representation.
Validation script outputs:
Run right one after another, without any change to the doc.
Errors found:
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)
Errors in parameters section
Parameters {'decimal', 'sep', 'compression', 'date_format', 'doublequote', 'header', 'na_rep', 'quoting', 'line_terminator', 'quotechar', 'encoding', 'tupleize_cols', 'mode', 'chunksize', 'escapechar', 'index_label', 'float_format', 'columns', 'index'} not documented
Unknown parameters {"'``"}
Parameter "path_or_buf" description should start with capital letter
Parameter "path_or_buf" description should finish with "."
Parameter "'``" has no type
Parameter "'``" description should start with capital letter
Parameter "'``" description should finish with "."
No returns section found
Errors found:
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)
Errors in parameters section
Parameters {'index_label', 'float_format', 'decimal', 'header', 'encoding', 'chunksize', 'na_rep', 'doublequote', 'quotechar', 'sep', 'compression', 'tupleize_cols', 'quoting', 'line_terminator', 'date_format', 'mode', 'columns', 'escapechar', 'index'} not documented
Unknown parameters {"'``"}
Parameter "path_or_buf" description should start with capital letter
Parameter "path_or_buf" description should finish with "."
Parameter "'``" has no type
Parameter "'``" description should start with capital letter
Parameter "'``" description should finish with "."
No returns section found
Expected Output
Issues found:
- Docstring cannot start in the new line: when this is met, I got the following error:
Traceback (most recent call last):
File "scripts/validate_docstrings.py", line 499, in <module>
sys.exit(main(args.function))
File "scripts/validate_docstrings.py", line 485, in main
return validate_one(function)
File "scripts/validate_docstrings.py", line 411, in validate_one
doc.summary.split(' ')[0][-1] == 's'):
IndexError: string index out of range
sep
is clearly documented, as far as I can say following section-3-parameters here;- "Not documented" parameters list changes with each script run;
Unknown parameters {"'``"}
is caused byline_terminator : str, default ``'\n'```, kind of fixed with
line_terminator : str, default '\n'`, but this also doesn't seem to be correct;- Some other description issues like those with
path_or_buf
, which seem to be correct (?); - Return section seems to be optional ("If the method returns a value, it will be documented in this section." here, but the script lists this as error "No returns section found".
Output of pd.show_versions()
INSTALLED VERSIONS
commit: 2ec022f
python: 3.6.4.final.0
python-bits: 64
OS: Windows
OS-release: 10
machine: AMD64
processor: Intel64 Family 6 Model 142 Stepping 9, GenuineIntel
byteorder: little
LC_ALL: None
LANG: None
LOCALE: None.None
pandas: 0.23.0.dev0+539.g2ec022f0d.dirty
Metadata
Metadata
Assignees
Labels
No labels