Skip to content

read_csv Documentation Rendering Poorly #22057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
WillAyd opened this issue Jul 25, 2018 · 9 comments
Closed

read_csv Documentation Rendering Poorly #22057

WillAyd opened this issue Jul 25, 2018 · 9 comments
Labels
Docs good first issue IO CSV read_csv, to_csv
Milestone
0.24.0

Comments

@WillAyd
Copy link
Member

WillAyd commented Jul 25, 2018

Looks like the filepath_or_buffer argument is rendering poorly in the read_csv documentation:

image

Should be a pretty easy doc fix:

pandas/pandas/io/parsers.py

Line 63 in edb71fd

filepath_or_buffer : str, pathlib.Path, py._path.local.LocalPath or any \

@WillAyd WillAyd added this to the Contributions Welcome milestone Jul 25, 2018
@gfyoung
Copy link
Member

gfyoung commented Jul 25, 2018 •
edited
Loading

Seems to be a change in the rendering code (here / upstream). That line hasn't changed in awhile. It looks fine in the 0.22.0 docs, but looks like what you posted starting in 0.23.0.

That being said, I generally prefer one-liner data type descriptions, so we can take this opportunity to shorten it for ease of reading anyhow.

@WillAyd
Copy link
Member Author

WillAyd commented Jul 25, 2018

@gfyoung that's correct, though I'm under the impression that we may have just been getting lucky previously. I'm not sure of any other docstring that has a continuation like that so I'm under the impression that's what needs to be fixed, but lmk if you have other ideas

@gfyoung
Copy link
Member

gfyoung commented Jul 25, 2018

@WillAyd : Oh, I agree that we can reword this. I'll put up a PR shortly.

gfyoung added a commit to forking-repos/pandas that referenced this issue Jul 25, 2018
@gfyoung
Reword doc for filepath_or_buffer in read_csv
e0ff490 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes pandas-devgh-22057.
gfyoung added a commit to forking-repos/pandas that referenced this issue Jul 25, 2018
@gfyoung
DOC: Reword doc for filepath_or_buffer in read_csv
45a1517 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes pandas-devgh-22057.
@gfyoung gfyoung added the IO CSV read_csv, to_csv label Jul 25, 2018
@gfyoung gfyoung mentioned this issue Jul 25, 2018
Merged
@gfyoung gfyoung modified the milestones: Contributions Welcome, 0.24.0 Jul 25, 2018
gfyoung added a commit to forking-repos/pandas that referenced this issue Jul 25, 2018
@gfyoung
DOC: Reword doc for filepath_or_buffer in read_csv
1599a73 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes pandas-devgh-22057.
@jorisvandenbossche
Copy link
Member

Normally such continuation lines should work, that is the general solution in case you need a multi-line (in essence a single line due to the \ :)) type description.

Maybe it has to do with the fact that it is a raw (r""") string?

@gfyoung
Copy link
Member

gfyoung commented Jul 26, 2018

@jorisvandenbossche : Right. Hard to tell since we never changed it since 0.22.0 at least (and it "breaks" in the 0.23.0 docs even though nothing happened to that line AFAICT).

@jorisvandenbossche
Copy link
Member

Well, looking at the blame, we actually did change that the last months: https://github.com/pandas-dev/pandas/pull/18968/files

@gfyoung
Copy link
Member

gfyoung commented Jul 26, 2018

Ah...hmm...I didn't notice that. 🙂 - would be surprised if that was the cause, but I think the actual PR is a better solution. 🙂

gfyoung added a commit to forking-repos/pandas that referenced this issue Jul 26, 2018
@gfyoung
DOC: Reword doc for filepath_or_buffer in read_csv
92cc578 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes pandas-devgh-22057.
@jorisvandenbossche
Copy link
Member

Why would you be surprised? The raw means that things like \ are in the actual string, instead of interpreted (to make it a single line)

(but I fully agree your PR is a big improvement in the explanation of the parameter! which makes this work-around unnecessary)

@gfyoung
Copy link
Member

gfyoung commented Jul 26, 2018 •
edited
Loading

Why would you be surprised? The raw means that things like \ are in the actual string, instead of interpreted (to make it a single line)

🤦‍♂️ - oh right, of course! I completely forgot that fact 🙂

jorisvandenbossche pushed a commit that referenced this issue Jul 27, 2018
@gfyoung @jorisvandenbossche
DOC: Reword doc for filepath_or_buffer in read_csv (#22058)
dfd58e8 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes gh-22057.
Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this issue Oct 1, 2018
@gfyoung
DOC: Reword doc for filepath_or_buffer in read_csv (pandas-dev#22058)
c6f642c 
Shortens dtype description following colon and
moves it to a more expanded parameter description.

Closes pandas-devgh-22057.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Docs good first issue IO CSV read_csv, to_csv
Projects
None yet
Milestone
0.24.0
Development

No branches or pull requests
3 participants
@WillAyd @jorisvandenbossche @gfyoung