DOC: Docstrings Formatting Error PR09

[HughKelley]

Validation error PR09 (Parameter description should end with "."). Removing this issue from the code base enables the addition to the CI for automated testing in the future.

If you are working on this issue, it probably makes sense to check for error PR08 in issue #25232 as well since they require similar changes.

PR09 has 445 occurrences (see #27977 )

Todo:

• get rid of the errors in the code base
• update the code_check.sh script to take into account the PR09 type of errors

[josibake]

I am planning to work on this, specifically the Timeseries class:

pandas.Timestamp.ceil: Parameter "ambiguous" description should finish with "."
pandas.Timestamp.ceil: Parameter "nonexistent" description should finish with "."
pandas.Timestamp.day_name: Parameter "locale" description should finish with "."
pandas.Timestamp.floor: Parameter "ambiguous" description should finish with "."
pandas.Timestamp.floor: Parameter "nonexistent" description should finish with "."
pandas.Timestamp.fromordinal: Parameter "ordinal" description should finish with "."
pandas.Timestamp.fromordinal: Parameter "freq" description should finish with "."
pandas.Timestamp.month_name: Parameter "locale" description should finish with "."
pandas.Timestamp.now: Parameter "tz" description should finish with "."
pandas.Timestamp.round: Parameter "ambiguous" description should finish with "."
pandas.Timestamp.round: Parameter "nonexistent" description should finish with "."
pandas.Timestamp.today: Parameter "tz" description should finish with "."
pandas.Timestamp.tz_localize: Parameter "ambiguous" description should finish with "."
pandas.Timestamp.tz_localize: Parameter "nonexistent" description should finish with "."
pandas.Timestamp.tz_localize: Parameter "errors" description should finish with "."

However, I need a little guidance regarding parameter descriptions. Take ceil , for example:

Parameters
----------
freq : a freq string indicating the ceiling resolution
ambiguous : bool, 'NaT', default 'raise'
            - bool contains flags to determine if time is dst or not (note
              that this flag is only applicable for ambiguous fall dst dates)
            - 'NaT' will return NaT for an ambiguous time
            - 'raise' will raise an AmbiguousTimeError for an ambiguous time

            .. versionadded:: 0.24.0

The description has this bulleted list and I can't find anything in the numpy docstring or pandas docstring guides about this. Is it okay to have these lists? If so, what is the correct way to format them? If not, is it better to just have a sentence description per value?

[josibake]

after reading contributing_docstring.html#section-3-parameters a little more carefully, I came up with this:

Parameters
----------
freq : a freq string indicating the ceiling resolution
ambiguous : {'raise', 'NaT', bool}, default 'raise'
            Specify how to handle ambiguous cases. bool contains flags to
            determine if time is dst or not (note that this flag is only
            applicable for ambiguous fall dst dates). 'NaT' will return NaT for
            an ambiguous time. 'raise' will raise an AmbiguousTimeError for an
            ambiguous time.

            .. versionadded:: 0.24.0

this passes the PR09 test. @datapythonista thoughts? do we care all that much how the docstrings are formatted so long as they are passing the validation?

[datapythonista]

We care about the docstring having the right content and following the standards for consistency and correct rendering. The script is an attempt to help us with that, so we're surely not happy by the script saying that things are ok.

freq got the decription where there should be the type. And the indentation of the description of ambiguous seems too much (should be 4 spaces).

Feel free to improve the validation script to try to capture these problems (wrong indentation, and lack of parameter description).

[josibake]

working on pandas.plotting:

pandas.plotting.andrews_curves: Parameter "frame" description should finish with "."
pandas.plotting.andrews_curves: Parameter "color" description should finish with "."
pandas.plotting.andrews_curves: Parameter "kwds" description should finish with "."
pandas.plotting.autocorrelation_plot: Parameter "kwds" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "class_column" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "cols" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "ax" description should start with a capital letter
pandas.plotting.parallel_coordinates: Parameter "ax" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "color" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "use_columns" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "xticks" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "axvlines" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "axvlines_kwds" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "sort_labels" description should finish with "."
pandas.plotting.parallel_coordinates: Parameter "kwds" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "alpha" description should start with a capital letter
pandas.plotting.scatter_matrix: Parameter "alpha" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "figsize" description should start with a capital letter
pandas.plotting.scatter_matrix: Parameter "figsize" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "grid" description should start with a capital letter
pandas.plotting.scatter_matrix: Parameter "grid" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "diagonal" description should start with a capital letter
pandas.plotting.scatter_matrix: Parameter "diagonal" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "marker" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "hist_kwds" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "density_kwds" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "range_padding" description should start with a capital letter
pandas.plotting.scatter_matrix: Parameter "range_padding" description should finish with "."
pandas.plotting.scatter_matrix: Parameter "kwds" description should finish with "."
pandas.plotting.table: Parameter "data" description should start with a capital letter
pandas.plotting.table: Parameter "data" description should finish with "."
pandas.plotting.table: Parameter "kwargs" description should start with a capital letter

[josibake]

working on pandas.DataFrame (#28702 )

[jb8429]

Working on pandas.Series #28738