DOC: cleanup docstring for read_json and fix error in contribution guide

[mpmoran]

• closes #xxxx

• tests added / passed

• passes git diff upstream/master -u -- "*.py" | flake8 --diff

• whatsnew entry

• Contribution Guide

  • fix incorrect paths to doc folder

• read_json()

  • add period to end of sentences
  • conform parameter types to project standard
  • add newlines for readability and consistency
  • for convert_dates parameter, fix typos and malformed description and add list as accepted type
  • make Returns section conform to project standard

[jreback]

cc @datapythonista

[jorisvandenbossche]

Looks good to me, thanks!

You will need to merge master to resolve the conflicts

[jorisvandenbossche]

Suggested change

	orient : str,
	orient : str

[mpmoran]

I think the preferred change, according to the docs, would be str, optional. However, the (many) other parameters in the docstring just put the default value. I will make it read str, default None for consistency's sake. I'll leave trudging through the function code and conforming the other parameter descriptions to the preferred style for another day . . .

[datapythonista]

Looks good, thanks for the fixes in the contributing guide. Did you check that ./scripts/validate_docstrings.py pandas.read_json doesn't report any error?

[datapythonista]

Our standard is to leave just the type Series or DataFrame in this line, and in the next indented to add any explanation. If you can update here, that would be great.

[mpmoran]

Will do.

[mpmoran]

• New changes to read_json docstring in a92642d:
  • Remove colon after default for path_or_buf parameter
  • Add default value for orient parameter (addresses hanging comma, see comment above)
  • Fix error on typ parameter by adding set of accepted values and a description
  • Fix error in Returns section by moving description to second line (see comment above)
  • Fix error in See Also section by adding description to DataFrame.to_json (see comment above)
  • Add Series.to_json to See Also section

[datapythonista]

Regarding the examples, if you can open an issue for those that would be great. I don't have a solution for that right now, will require some research.

The default None vs optional we do the following. If the None means None like you're specifying a fill value and the default is filling with None values, when we use default None. If None means doesn't apply, don't do whatever... then we use optional. For example, in the chunksize, None means do not chunk, not a chunk size, so that should be optional. If you don't mind fixing those.

Also, when we specify list, if it makes sense, better to use list of str...

For the rest looks good. Thanks!

[mpmoran]

Issue has been opened. #27308

And the fixes to the type hints have been made.

[jreback]

can you merge master

[mpmoran]

Done.

[TomAugspurger]

Thanks @mpmoran!