DOC: "getting started" under "coming from SQL" assumes you're using a notebook

[mattwelke]

Location of the documentation

https://pandas.pydata.org/docs/getting_started/comparison/comparison_with_sql.html

Documentation problem

I'm getting started with Pandas. I went to the docs site and found a section called "getting started" which sounded good to me. It then had a few boxes for where you're coming from and one of them was "coming from SQL" which also sounded good for me. I'm a back end dev. I was able to make a Python script (I'm using VS Code) that imported the library and ran the commands, but I saw no output. The docs showed output from tips.head(), but I saw no output from that line when I ran my script.

Googling my issue, I found this: https://stackoverflow.com/questions/51580863/output-of-pandas-head-function-is-not-displayed

The accepted answer suggested running print(df.head()) instead of just df.head(). That worked for me. After reading that Stack Overflow page, I remembered that people also often use pandas with notebooks, so I went back to the docs page and looked at it closely. At that point, I noticed the In [5]: near the steps. I think people who've never used notebooks at all before might not even recognize this.

Suggested fix for documentation

• Remove the requirement to run the getting started code in a notebook, or
• Include alternative line for those running the script as is without viz tools like notebooks, or
• Add warning at top of getting started guide that readers are required to setup a notebook and run the code in it for their experience to match that of the guide

[afeld]

Mmm, good point. This isn't specific to the SQL page, so maybe we write up a "how to read these docs" section before the Getting Started Tutorials (hierarchically), since those and the Comparison documentation all use iPython output? Not sure that would warrant its own page, but not seeing another obvious place to put it.

[mattwelke]

It makes sense to me. I felt kind of silly as I wrote this ticket, because I was able to sort out my issue myself. It was an obvious solution (go check out notebooks, or figure out what notebook specific code is here to remove). But I've worked as a dev professionally for a few years. I was just thinking from the perspective of someone a lot newer who might encounter this as one of their earliest programming getting started guides, and figured it was a good idea to make the ticket.

I like the idea of a page people can visit to get prerequisite info. Maybe instead of demanding people go through it, we keep the nice use case-oriented style it has now where people jump right into guides like this SQL one, by having a link at the top of the page to the prerequisite info page. That page could explain that samples are meant to be run in notebooks and include some steps for people to get a notebook spun up or access a remote one on a cloud service.

[rhuille]

No worries, I think your question was logical, lots of people may have the same issue ! What do you think 🔝 ? :)

[mattwelke]

@rhuille Looks great! In fact I didn't even realize til reading that now that only the last line in a block run in a notebook has output. So it would help readers like me. :)

[bsun94]

Hi guys, I'm still quite new to contributing to pandas, I was wondering if any help was still needed here?