Skip to content

Docstring validation script issues #20318

Closed
@m-dz

Description

@m-dz

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:

  1. 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
  1. sep is clearly documented, as far as I can say following section-3-parameters here;
  2. "Not documented" parameters list changes with each script run;
  3. Unknown parameters {"'``"} is caused by line_terminator : str, default ``'\n'```, kind of fixed with line_terminator : str, default '\n'`, but this also doesn't seem to be correct;
  4. Some other description issues like those with path_or_buf, which seem to be correct (?);
  5. 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

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions