DOC: Fix formatting of parameters

[datapythonista]

In the pandas API documentation, when the parameters are defined, they should be defined as:

Parameters
----------
name : str
    Description of the name parameter

Note that in name : str there is one space before the colon, and one after. This is important, because when the html documentation is rendered, if those spaces are not found, the name of the parameter is not splitted from the type, and everything is rendered as if everything was the name.

See for example in the bins parameter of Series.hist (note that in this case there are two of them, and the second should be removed, instead of fixing the spaces).

This happens in many docstrings, and it should be fixed to ensure that the documentation is rendered correctly.

We have a script to generate the whole list or cases where this happens:

./scripts/validate_docstrings.py --errors=PR10
pandas.read_msgpack: Parameter "encoding" requires a space before the colon separating the parameter name and type
pandas.read_excel: Parameter "engine" requires a space before the colon separating the parameter name and type
pandas.ExcelWriter: Parameter ".. versionadded" requires a space before the colon separating the parameter name and type
pandas.read_json: Parameter "chunksize" requires a space before the colon separating the parameter name and type
pandas.HDFStore.append: Parameter "format" requires a space before the colon separating the parameter name and type
pandas.read_feather: Parameter "use_threads" requires a space before the colon separating the parameter name and type
pandas.read_parquet: Parameter "columns" requires a space before the colon separating the parameter name and type
pandas.Series.asfreq: Parameter "fill_value" requires a space before the colon separating the parameter name and type
pandas.Series.plot.hist: Parameter "bins" requires a space before the colon separating the parameter name and type
pandas.Series.hist: Parameter "bins" requires a space before the colon separating the parameter name and type
pandas.Series.to_string: Parameter "header" requires a space before the colon separating the parameter name and type
pandas.DataFrame.asfreq: Parameter "fill_value" requires a space before the colon separating the parameter name and type
pandas.DataFrame.from_csv: Parameter "infer_datetime_format" requires a space before the colon separating the parameter name and type
pandas.Panel.asfreq: Parameter "fill_value" requires a space before the colon separating the parameter name and type
pandas.DatetimeIndex.to_perioddelta: Parameter "freq" requires a space before the colon separating the parameter name and type
pandas.TimedeltaIndex: Parameter "unit" requires a space before the colon separating the parameter name and type
pandas.Period.to_timestamp: Parameter "how" requires a space before the colon separating the parameter name and type
pandas.Timestamp.replace: Parameter "nanosecond" requires a space before the colon separating the parameter name and type
pandas.tseries.offsets.SemiMonthEnd: Parameter "n" requires a space before the colon separating the parameter name and type
pandas.tseries.offsets.SemiMonthEnd: Parameter "day_of_month" requires a space before the colon separating the parameter name and type
pandas.tseries.offsets.SemiMonthBegin: Parameter "n" requires a space before the colon separating the parameter name and type
pandas.tseries.offsets.SemiMonthBegin: Parameter "day_of_month" requires a space before the colon separating the parameter name and type
pandas.core.groupby.DataFrameGroupBy.boxplot: Parameter "subplots " requires a space before the colon separating the parameter name and type
pandas.core.resample.Resampler.asfreq: Parameter "fill_value" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "data" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "precision" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "table_styles" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "uuid" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "caption" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler: Parameter "cell_ids" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.format: Parameter "formatter" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.format: Parameter "subset" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_precision: Parameter "precision" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_table_styles: Parameter "table_styles" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_caption: Parameter "caption" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_properties: Parameter "subset" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_properties: Parameter "kwargs" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.set_uuid: Parameter "uuid" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_max: Parameter "subset" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_max: Parameter "color" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_max: Parameter "axis" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_min: Parameter "subset" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_min: Parameter "color" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_min: Parameter "axis" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.highlight_null: Parameter "null_color" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.background_gradient: Parameter "cmap" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.background_gradient: Parameter "low, high" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.background_gradient: Parameter "axis" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.background_gradient: Parameter "subset" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.background_gradient: Parameter "text_color_threshold" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.render: Parameter "`**kwargs`" requires a space before the colon separating the parameter name and type
pandas.io.formats.style.Styler.use: Parameter "styles" requires a space before the colon separating the parameter name and type
pandas.plotting.andrews_curves: Parameter "color" requires a space before the colon separating the parameter name and type
pandas.plotting.andrews_curves: Parameter "kwds" requires a space before the colon separating the parameter name and type
pandas.plotting.lag_plot: Parameter "series" requires a space before the colon separating the parameter name and type
pandas.plotting.lag_plot: Parameter "lag" requires a space before the colon separating the parameter name and type
pandas.plotting.lag_plot: Parameter "ax" requires a space before the colon separating the parameter name and type
pandas.plotting.lag_plot: Parameter "kwds" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "frame" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "class_column" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "cols" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "ax" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "color" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "use_columns" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "xticks" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "colormap" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "axvlines" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "axvlines_kwds" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "sort_labels" requires a space before the colon separating the parameter name and type
pandas.plotting.parallel_coordinates: Parameter "kwds" requires a space before the colon separating the parameter name and type
pandas.set_option: Parameter "value " requires a space before the colon separating the parameter name and type
pandas.api.types.union_categoricals: Parameter "ignore_order" requires a space before the colon separating the parameter name and type
pandas.Series.as_matrix: Parameter "columns" requires a space before the colon separating the parameter name and type
pandas.Series.from_csv: Parameter "infer_datetime_format" requires a space before the colon separating the parameter name and type
pandas.DataFrame.as_matrix: Parameter "columns" requires a space before the colon separating the parameter name and type
pandas.Panel.as_matrix: Parameter "columns" requires a space before the colon separating the parameter name and type

Calling the same script with the parameter --format=azure can be useful, as it reports also the file and the line where the function is defined. Python introspection is used to obtain them, and it probably won't be correct if the function is created dynamically, but it could be helpful in many cases. Using grep "encoding:" is also an option (encoding is the name of the parameter of the first detected failing case).

We should add all the missing spaces and fix all the formats. Executing the script after this has been done, should report no errors.

[alexander-ponomaroff]

I would like to work on this.

[hbrumley]

This probably isn't the right place to post this, but when I run the script I get an error:

./scripts/validate_docstrings.py:490: DtypeWarning: Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.
runner.run(test, out=f.write)

I'm not really sure what the issue is here. Is there a known solution or should I make a new issue?

[datapythonista]

Can you create a new issue following the template we provide? We need detailed information to understand the problem.

Feel free to mention me, and I'll take a look.

[alexander-ponomaroff]

@datapythonista I see that somebody took my issue haha. So I will not work on this anymore?

[alexander-ponomaroff]

@datapythonista Since there is already a pull request for this issue, would you be able to recommend something similar to this for me to work on over the weekend? I'm really interested in contributing to Pandas, however I'm having a hard time finding issues to work on because they get taken quickly and there is somebody working on most of the existing issues. Please let me know if there is something that I can work on that hasn't been filed as an issue yet. Thanks.

[datapythonista]

Improving the content of a whole docstring that doesn't look good is something always useful.

If you run validate_docstrings.py without parameters you will get a very long list of issues, everything should be fixed.

If you run flake8-rst on the docs, there are 2000 errors in the rst files that should also be fixed.

I keep creating issues, but you can create them yourself, or just sendP PRs for some fixes, no need for issue.

[alexander-ponomaroff]

@datapythonista Thank you, I will look into this and create some issues.