DOC: Fix code style in documentation

[dsaxton]

The docs use certain coding style conventions that are no longer used in pandas (e.g., we adopt black's opinions in terms of line wrapping and quoting), for instance https://pandas.pydata.org/pandas-docs/stable/user_guide/merging.html. We should update the docs to match current style preferences.

blacken-docs is a useful tool that can help in doing some of this formatting, but it has to be used carefully since it might render lines that are too long and will fail flake8-rst checks, or it may not be able to parse certain files because of nuances in how the docs are written (raw output or magic commands in code blocks). One approach is to comment out the erring lines, let the tool handle all the others, then finish the commented lines manually.

Example cleanup: https://github.com/pandas-dev/pandas/pull/36700/files

List of files that need updating (if you submit a PR be sure to link back to this issue):

doc/source/development:

• code_style.rst
• contributing.rst
• contributing_docstring.rst
• developer.rst
• extending.rst
• index.rst
• internals.rst
• maintaining.rst
• meeting.rst
• policies.rst
• roadmap.rst

doc/source/getting_started/comparison:

• comparison_with_r.rst
• comparison_with_sas.rst
• comparison_with_sql.rst
• comparison_with_stata.rst
• index.rst

doc/source/getting_started/intro_tutorials:

• 01_table_oriented.rst
• 02_read_write.rst
• 03_subset_data.rst
• 04_plotting.rst
• 05_add_columns.rst
• 06_calculate_statistics.rst
• 07_reshape_table_layout.rst
• 08_combine_dataframe.rst
• 09_timeseries.rst
• 10_text_data.rst

doc/source/getting_started:

• index.rst
• install.rst
• overview.rst
• tutorials.rst

doc/source/user_guide:

• 10min.rst
• advanced.rst
• basics.rst
• boolean.rst
• categorical.rst
• computation.rst
• cookbook.rst
• dsintro.rst
• duplicates.rst
• enhancingperf.rst
• gotchas.rst
• groupby.rst
• index.rst
• integer_na.rst
• io.rst
• merging.rst
• missing_data.rst
• options.rst
• reshaping.rst
• scale.rst
• sparse.rst
• text.rst
• timedeltas.rst
• timeseries.rst
• visualization.rst

[meghanacosmos]

I'd like to work on this @dsaxton.

[dsaxton]

I'd like to work on this.

Sure, feel free to submit a PR

[meghanacosmos]

Are there any docs you'd like me to fix first? @dsaxton

[dsaxton]

Are there any docs you'd like me to fix first? @dsaxton

Up to you, probably the best way would be to browse through the rst files in https://github.com/pandas-dev/pandas/tree/master/doc/source (the user_guide folder might be a good place to start) and check for code blocks that use "old style" formatting and update those. Any improvement is appreciated!

[erfannariman]

Files I reformatted in #36780 so others won't do double work:

• doc/source/getting_started/intro_tutorials/06_calculate_statistics.rst
• doc/source/getting_started/intro_tutorials/07_reshape_table_layout.rst
• doc/source/getting_started/intro_tutorials/08_combine_dataframes.rst
• doc/source/getting_started/intro_tutorials/09_timeseries.rst
• doc/source/getting_started/intro_tutorials/10_text_data.rst
• doc/source/user_guide/10min.rst
• doc/source/user_guide/sparse.rst

[mvoitko]

@dsaxton Any ideas about docs needed to be fixed first? I would like to contribute. I am also planning to hold a Hacktoberfest meetup and I am sure there would be some guys who would love to help pandas, so I would really appreciate it if you could make some kind of prioritized list of docs which should be fixed first.

[dsaxton]

@dsaxton Any ideas about docs needed to be fixed first? I would like to contribute. I am also planning to hold a Hacktoberfest meetup and I am sure there would be some guys who would love to help pandas, so I would really appreciate it if you could make some kind of prioritized list of docs which should be fixed first.

That would be awesome, @erfannariman put together a list of files (thank you!) that I just added to the OP

[erfannariman]

@dsaxton Any ideas about docs needed to be fixed first? I would like to contribute. I am also planning to hold a Hacktoberfest meetup and I am sure there would be some guys who would love to help pandas, so I would really appreciate it if you could make some kind of prioritized list of docs which should be fixed first.

As @dsaxton already mentioned here the user_guide is probably a good place to start.

[karasinski]

It looks like the following are already compliant with blacken and flake8 and need no additional formatting.

doc/source/development:

• contributing_docstring.rst
• developer.rst

doc/source/user_guide:

• boolean.rst
• categorical.rst
• index.rst
• integer_na.rst
• options.rst
• reshaping.rst
• timedeltas.rst

[karasinski]

Upon further inspection, it looks like doc/source/user_guide/text.rst is also fine as is.

[Mikhaylov-yv]

Sorry, did I do the right thing here or not? a3850c9

[dsaxton]

a3850c9

That looks fine aside from the line wrapping of dtypes (although this file has already been fixed)

[meghanacosmos]

Are there any docs you'd like me to fix first? @dsaxton

Up to you, probably the best way would be to browse through the rst files in https://github.com/pandas-dev/pandas/tree/master/doc/source (the user_guide folder might be a good place to start) and check for code blocks that use "old style" formatting and update those. Any improvement is appreciated!

Sure, thank you!

[skorani]

timedeltas.rst and timeseries.rst are fixed.

[SambhaviPD]

@dsaxton - Thought of contributing to this issue, went through most of the files in pandas/doc/source and found them to be formatted similar to https://github.com/pandas-dev/pandas/pull/36700/files. Is this whole list complete?

[dsaxton]

@dsaxton - Thought of contributing to this issue, went through most of the files in pandas/doc/source and found them to be formatted similar to https://github.com/pandas-dev/pandas/pull/36700/files. Is this whole list complete?

Yes I think everything is pretty much fixed, but will probably leave open for a little bit in case anything else shows up.

Edit: @SambhaviPD it looks like /user_guide/merging.rst still has issues if you wanted to work on those