DOC: Add code-formatting and cross-reference links to read_csv docstring

[tpaxman]

• Toward DOC: Inconsistent use of code-style formatting (backticks) in docstrings #53674 (specifically for pandas.read_csv for now).
• All code checks passed.

Added code formatting where applicable and added sphinx cross-referencing tags for any pandas classes or functions. Also cleaned up cases where "default None" was specified rather than "optional".

Note: I plan to submit future PRs focused on editing the content (e.g., #53673) but wanted to start with the formatting changes.

[mroeschke]

2023-06-20T05:01:47.5693361Z /home/runner/work/pandas/pandas/pandas/io/parsers/readers.py:docstring of pandas.io.parsers.readers.read_csv:176: WARNING: Bullet list ends without a blank line; unexpected unindent.
2023-06-20T05:01:47.5694692Z /home/runner/work/pandas/pandas/pandas/io/parsers/readers.py:docstring of pandas.io.parsers.readers.read_csv:178: ERROR: Unexpected indentation.
2023-06-20T05:01:47.5695421Z /home/runner/work/pandas/pandas/pandas/io/parsers/readers.py:docstring of pandas.io.parsers.readers.read_table:176: WARNING: Bullet list ends without a blank line; unexpected unindent.
2023-06-20T05:01:47.5696750Z /home/runner/work/pandas/pandas/pandas/io/parsers/readers.py:docstring of pandas.io.parsers.readers.read_table:178: ERROR: Unexpected indentation.

[tpaxman]

Thanks @mroeschke for the report on this. I am trying to have a closer look but ran into issue #53788 which I need to figure out before I can rebuild the docs I think. Also, just since I'm fairly new at this, is there a simple way to locate specific lines in a docstring (i.e. 176 and 178 that are being flagged)? It's not immediately obvious given that the docstring in the source code is built out of format strings (i.e. isn't a literal) so it makes it hard to know which lines are causing trouble just from reviewing the py source. Thanks for the help.

[tpaxman]

Hi @mroeschke, I located the error and fixed the formatting with the read_csv docstring. Hopefully that will have rectified this issue.

[tpaxman]

What is the meaning of the cancelled checks? Do I need to do something to re-run or was that intentional?

[mroeschke]

Thanks @tpaxman. The canceled checks are due to some unit tests that are unrelated

[Charlie-XIAO]

Sorry for chipping in @tpaxman. Though "pandas" is a module, IMHO it should not be enclosed in backticks here? I don't see it being considered inline code anywhere else in the docs either. (Just mentioning this because I see you making some doc contributions recently. Maybe you can make this change in one of your currently open PRs if you agree with my point).

Some other suggestions

1. I think lists should have spaces after the commas in [0,1,3].

2. Not sure but do you think these should be considered string literals? Currently its a bit hard to tell them apart because the quotation marks in text mode is small (especially that the empty string '' is hard to tell at first glance).

[tpaxman]

Thank you, @Charlie-XIAO! I agree with all your suggestions for sure. I was thinking about whether to convert that list of na_values to string literals and I think it would help readability. I can submit a follow up PR to address those.

As for the formatting for the pandas module, I am not totally clear on what is preferred in the docs since I've seen instances of both plain text and code-formatted versions. That might be something the maintainers could advise on. And if there is a preferred format, it would be good to have that added to the developer guide as well.