DOC: pd.read_csv doc-string clarification #11555

[frankcleary]

closes #11555
Updated IO Tools documentation for read_csv() and read_table() to be consistent with the doc-string,
also reordered keywords to group them more logically. Also updated merging.rst docs for concat.

[frankcleary]

Note the '' allows all the options to both obey the line character limit and be parsed into the html docs correctly. I'm not sure if it's a style we want or not.

[frankcleary]

Migrated from #11756

Here's what the IO docs would look like:

[jreback]

looks like a couple of linting errors

linting -> pandas/io
pandas/io/parsers.py:51:80: E501 line too long (80 > 79 characters)
pandas/io/parsers.py:54:80: E501 line too long (80 > 79 characters)
pandas/io/parsers.py:62:80: E501 line too long (80 > 79 characters)
pandas/io/parsers.py:67:80: E501 line too long (80 > 79 characters)

[frankcleary]

Fixed long line lint errors.

[jorisvandenbossche]

Can you use the top-level namespace here? So just :func:~pandas.read_csv (actually `:func:`read_csv will work as well and even cleaner)

[frankcleary]

Makes sense, updated throughout the file.

[jreback]

ok, ping when green.

I think we can merge this.

@jorisvandenbossche ok ?

[jreback]

@frankcleary actually, pls add a note in whatsnew, maybe in Enhancements (with a link to the docs)

[jreback]

thanks @frankcleary

when docs are built (prob a few hours), have a look: http://pandas-docs.github.io/pandas-docs-travis/

and if needed pls issue a follow up to correct

[jreback]

@frankcleary looks good!

@jorisvandenbossche
was wondering if we should put references (this for io.rst) in the 'doc-string' area to some of the examples
e.g. http://pandas-docs.github.io/pandas-docs-travis/io.html#na-values could be linked from the na_values option.

?