Skip to content

DOC: Capitalize docstring summaries #23881

@datapythonista

Description

@datapythonista

Our standard is to start the docstrings with a capital letter (and finish them with a period).

We'll shortly add a check to make sure that new contributions follow this standard. But before we can do that, we need to fix the many cases that are already wrong.

In this issue we should fix all the remaining cases where the docstring summary starts with a lower case letter. This is the command to generate them (which should return nothing after the fix), and the list of current issues.

$ ./scripts/validate_docstrings.py --errors=SS02
pandas.io.json.json_normalize: Summary does not start with a capital letter
pandas.HDFStore.info: Summary does not start with a capital letter
pandas.melt: Summary does not start with a capital letter
pandas.Series.argmin: Summary does not start with a capital letter
pandas.Series.argmax: Summary does not start with a capital letter
pandas.DataFrame.melt: Summary does not start with a capital letter
pandas.DataFrame.to_feather: Summary does not start with a capital letter
pandas.Index.values: Summary does not start with a capital letter
pandas.Index.is_monotonic: Summary does not start with a capital letter
pandas.Index.is_monotonic_increasing: Summary does not start with a capital letter
pandas.Index.is_monotonic_decreasing: Summary does not start with a capital letter
pandas.Index.is_unique: Summary does not start with a capital letter
pandas.Index.dtype: Summary does not start with a capital letter
pandas.Index.dtype_str: Summary does not start with a capital letter
pandas.Index.inferred_type: Summary does not start with a capital letter
pandas.Index.where: Summary does not start with a capital letter
pandas.Index.take: Summary does not start with a capital letter
pandas.Index.putmask: Summary does not start with a capital letter
pandas.Index.ravel: Summary does not start with a capital letter
pandas.Index.join: Summary does not start with a capital letter
pandas.Index.asof_locs: Summary does not start with a capital letter
pandas.Index.contains: Summary does not start with a capital letter
pandas.Index.get_indexer_for: Summary does not start with a capital letter
pandas.RangeIndex.from_range: Summary does not start with a capital letter
pandas.MultiIndex.to_hierarchical: Summary does not start with a capital letter
pandas.Timestamp.ceil: Summary does not start with a capital letter
pandas.Timestamp.combine: Summary does not start with a capital letter
pandas.Timestamp.floor: Summary does not start with a capital letter
pandas.Timestamp.fromordinal: Summary does not start with a capital letter
pandas.Timestamp.fromtimestamp: Summary does not start with a capital letter
pandas.Timestamp.replace: Summary does not start with a capital letter
pandas.Timestamp.strftime: Summary does not start with a capital letter
pandas.Timestamp.strptime: Summary does not start with a capital letter
pandas.Timedelta.view: Summary does not start with a capital letter
pandas.Timedelta.ceil: Summary does not start with a capital letter
pandas.Timedelta.floor: Summary does not start with a capital letter
pandas.Timedelta.to_pytimedelta: Summary does not start with a capital letter
pandas.tseries.offsets.Tick: Summary does not start with a capital letter
pandas.tseries.offsets.Day: Summary does not start with a capital letter
pandas.tseries.offsets.Hour: Summary does not start with a capital letter
pandas.tseries.offsets.Minute: Summary does not start with a capital letter
pandas.tseries.offsets.Second: Summary does not start with a capital letter
pandas.tseries.offsets.Milli: Summary does not start with a capital letter
pandas.tseries.offsets.Micro: Summary does not start with a capital letter
pandas.tseries.offsets.Nano: Summary does not start with a capital letter
pandas.core.window.Rolling.max: Summary does not start with a capital letter
pandas.core.window.Rolling.cov: Summary does not start with a capital letter
pandas.core.window.Rolling.apply: Summary does not start with a capital letter
pandas.core.window.Rolling.quantile: Summary does not start with a capital letter
pandas.core.window.Expanding.max: Summary does not start with a capital letter
pandas.core.window.Expanding.cov: Summary does not start with a capital letter
pandas.core.window.Expanding.apply: Summary does not start with a capital letter
pandas.core.window.Expanding.quantile: Summary does not start with a capital letter
pandas.core.window.EWM.mean: Summary does not start with a capital letter
pandas.core.window.EWM.std: Summary does not start with a capital letter
pandas.core.window.EWM.var: Summary does not start with a capital letter
pandas.core.window.EWM.corr: Summary does not start with a capital letter
pandas.core.window.EWM.cov: Summary does not start with a capital letter
pandas.core.groupby.GroupBy.groups: Summary does not start with a capital letter
pandas.core.groupby.GroupBy.indices: Summary does not start with a capital letter
pandas.core.resample.Resampler.groups: Summary does not start with a capital letter
pandas.core.resample.Resampler.indices: Summary does not start with a capital letter
pandas.core.resample.Resampler.asfreq: Summary does not start with a capital letter
pandas.io.formats.style.Styler.clear: Summary does not start with a capital letter
pandas.Panel.items: Summary does not start with a capital letter
pandas.Panel.major_axis: Summary does not start with a capital letter
pandas.Panel.minor_axis: Summary does not start with a capital letter

Ignore Series.argmin and Series.argmax, as the docstring is autogenerated, and it's not trivial to fix. And other similar cases, if any.

In some cases the problem is that there is a deprecated directive .. deprecated:: at the beginning of te docstring. This is wrong too, and the deprecation should be after the short summary (the first line/paragraph of the summary).

While this issue is mainly to make the first letter in the summary a capital letter, for the cases where we fix this, would be nice to also add a period at the end of the paragraph, if there is not got one already.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions