DOC: Docstrings Formatting Error PR09 #28602

HughKelley · 2019-09-24T21:40:47Z

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

The text was updated successfully, but these errors were encountered:

josibake · 2019-09-27T17:30:12Z

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 · 2019-09-27T18:17:43Z

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 · 2019-09-28T11:57:33Z

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 · 2019-09-30T14:56:42Z

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 · 2019-10-01T03:15:49Z

working on pandas.DataFrame (#28702 )

jb8429 · 2019-10-01T19:19:18Z

Working on pandas.Series #28738

HughKelley · 2019-10-15T18:51:30Z

17 PR09 errors remaining in the code are listed below.

./scripts/validate_docstrings.py --errors=PR09

Some of these are already being worked on in open issues

pandas.io.formats.style.Styler: Parameter "na_rep" description should finish with "."
pandas.io.formats.style.Styler.format: Parameter "formatter" description should finish with "."
pandas.io.formats.style.Styler.format: Parameter "na_rep" description should finish with "."
pandas.DataFrame.corr: Parameter "method" description should finish with "."
pandas.DataFrame.to_hdf: Parameter "format" description should finish with "."
pandas.DataFrame.to_sql: Parameter "con" description should finish with "."
pandas.core.groupby.DataFrameGroupBy.corr: Parameter "method" description should finish with "."
pandas.core.window.rolling.Rolling.apply: Parameter "engine" description should finish with "."
pandas.core.window.rolling.Rolling.apply: Parameter "engine_kwargs" description should finish with "."
pandas.core.window.expanding.Expanding.apply: Parameter "engine" description should finish with "."
pandas.core.window.expanding.Expanding.apply: Parameter "engine_kwargs" description should finish with "."
pandas.eval: Parameter "truediv" description should finish with "."
pandas.Series.to_hdf: Parameter "format" description should finish with "."
pandas.Series.to_sql: Parameter "con" description should finish with "."
pandas.read_excel: Parameter "usecols" description should finish with "."
pandas.read_sql: Parameter "con" description should finish with "."
pandas.PeriodIndex: Parameter "freq" description should finish with "."

TomAugspurger · 2020-01-08T22:16:33Z

Remaining:

pandas.Series.to_hdf: Parameter "format" description should finish with "."
pandas.Series.to_sql: Parameter "con" description should finish with "."
pandas.read_excel: Parameter "usecols" description should finish with "."
pandas.read_sql: Parameter "con" description should finish with "."
pandas.testing.assert_categorical_equal: Parameter "check_dtype" description should finish with "."
pandas.testing.assert_categorical_equal: Parameter "obj" description should finish with "."
pandas.testing.assert_extension_array_equal: Parameter "left" description should finish with "."
pandas.testing.assert_extension_array_equal: Parameter "right" description should finish with "."
pandas.testing.assert_interval_array_equal: Parameter "obj" description should finish with "."
pandas.testing.assert_sp_array_equal: Parameter "check_fill_value" description should finish with "."
pandas.eval: Parameter "truediv" description should finish with "."
pandas.PeriodIndex: Parameter "freq" description should finish with "."
pandas.core.window.rolling.Rolling.apply: Parameter "engine" description should finish with "."
pandas.core.window.rolling.Rolling.apply: Parameter "engine_kwargs" description should finish with "."
pandas.core.window.expanding.Expanding.apply: Parameter "engine" description should finish with "."
pandas.core.window.expanding.Expanding.apply: Parameter "engine_kwargs" description should finish with "."
pandas.core.groupby.DataFrameGroupBy.corr: Parameter "method" description should finish with "."
pandas.io.formats.style.Styler: Parameter "na_rep" description should finish with "."
pandas.io.formats.style.Styler.format: Parameter "formatter" description should finish with "."
pandas.io.formats.style.Styler.format: Parameter "na_rep" description should finish with "."
pandas.DataFrame.corr: Parameter "method" description should finish with "."
pandas.DataFrame.to_hdf: Parameter "format" description should finish with "."
pandas.DataFrame.to_sql: Parameter "con" description should finish with "."

mroeschke · 2021-11-25T18:43:51Z

PRO9 is currently specified in ci/code_checks.sh so closing

HughKelley changed the title ~~Docstrings Formatting Error PR09~~ DOC: Docstrings Formatting Error PR09 Sep 27, 2019

HughKelley mentioned this issue Sep 27, 2019

DOC: Styler errors PR08 and PR09 #28656

Closed

josibake mentioned this issue Sep 29, 2019

DOCS: fix PR09,PR09 doc string errors in Timestamp, NaT, Timedelta class #28673

Closed

jb8429 mentioned this issue Oct 1, 2019

DOC: Fixing docstrings formatting error PR08, PR09 in pandas.Series #28738

Closed

simonjayhawkins added the Docs label Oct 8, 2019

This was referenced Oct 18, 2019

DOCS: Errors PR08 PR09 in pandas.Period #29073

Closed

DOCS: docstrings formatting errors in pandas.PeriodIndex #29204

Closed

This was referenced Oct 26, 2019

DOCS: Formatting Errors pandas.TimedeltaIndex #29236

Closed

Pr09 batch 1 #29324

Merged

This was referenced Nov 4, 2019

PR09 Batch 2 #29396

Merged

Pr09 batch 3 #29434

Merged

PR09 batch 4 #29466

Merged

DOC: Fixes to docstrings, mainly PR09 errors #29530

Closed

jreback added this to the 1.0 milestone Nov 13, 2019

HughKelley mentioned this issue Jan 2, 2020

DOC: Fixing PR09 formatting errors #30622

Merged

2 tasks

TomAugspurger modified the milestones: 1.0, Contributions Welcome Jan 8, 2020

mroeschke added the good first issue label Jul 21, 2021

marvintensuan mentioned this issue Aug 27, 2021

DOC PR09 Add "." on to_hdf format parameter #43246

Merged

4 tasks

Varun270 mentioned this issue Nov 14, 2021

Added "." on to check_dtype and obj parameter #44446

Merged

MarcoGorelli mentioned this issue Nov 15, 2021

beginner issues MarcoGorelli/pyladieslondon-sprints#40

Closed

mroeschke closed this as completed Nov 25, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Docstrings Formatting Error PR09 #28602

DOC: Docstrings Formatting Error PR09 #28602

HughKelley commented Sep 24, 2019 •

edited

Loading

josibake commented Sep 27, 2019 •

edited

Loading

josibake commented Sep 27, 2019

datapythonista commented Sep 28, 2019

josibake commented Sep 30, 2019 •

edited

Loading

josibake commented Oct 1, 2019

jb8429 commented Oct 1, 2019

HughKelley commented Oct 15, 2019 •

edited

Loading

TomAugspurger commented Jan 8, 2020

mroeschke commented Nov 25, 2021

DOC: Docstrings Formatting Error PR09 #28602

DOC: Docstrings Formatting Error PR09 #28602

Comments

HughKelley commented Sep 24, 2019 • edited Loading

josibake commented Sep 27, 2019 • edited Loading

josibake commented Sep 27, 2019

datapythonista commented Sep 28, 2019

josibake commented Sep 30, 2019 • edited Loading

josibake commented Oct 1, 2019

jb8429 commented Oct 1, 2019

HughKelley commented Oct 15, 2019 • edited Loading

TomAugspurger commented Jan 8, 2020

mroeschke commented Nov 25, 2021

HughKelley commented Sep 24, 2019 •

edited

Loading

josibake commented Sep 27, 2019 •

edited

Loading

josibake commented Sep 30, 2019 •

edited

Loading

HughKelley commented Oct 15, 2019 •

edited

Loading