Make it clearer guides use notebook environment

[OmegaTwiddle]

URL to the relevant documentation

I'm following the tutorial at https://docs.quantum.ibm.com/guides/hello-world

If I follow Step 1 line for line, my script just exits without printing or displaying anything.

Select all that apply

• typo
• code bug
• out-of-date content
• broken link
• other

Describe the fix.

I needed to add the below code to get it to show anything (this wasn't obvious to me).

import matplotlib.pyplot as plt 
plt.show()

[frankharkins]

Hi @OmegaTwiddle, how are you running the code examples?

I've seen this confusion before when users run code examples in a Python script: Our documentation is written in Jupyter notebooks. In notebooks, the output of the last line of a cell is displayed right after the cell. In the case of qc.draw(), the output is a matplotlib figure, which has a rich representation (image). That's why you see the image immediately after the cell.

I do wonder if there's a way we can make this clearer to users though.

EDIT: I've since realised we do have a comment about that in the same code cell:

# Return a drawing of the circuit using MatPlotLib ("mpl"). This is the
# last line of the cell, so the drawing appears in the cell output.
# Remove the "mpl" argument to get a text drawing.

Do you remember if you saw this comment? I'm wondering how we could make it clearer to future readers.

[OmegaTwiddle]

I see. Yeah I am using a standalone script on my machine, and running via python from the command line.

I did read and try the suggestion in the comment. Even removing the argument didn't draw a text drawing to the screen, so the comment isn't accurate for those running it as a script.

It may depend on your user base (perhaps very few people are running scripts), but I find them easier to setup than Jupyter notebooks. I might recomment updating the language that says "It is recommended that you use the Jupyter development environment to interact with quantum computers." to something more like "This tutorial is designed for Jupyter development experience, etc etc". When I read the first statement, since I was running locally (and not interacting with quantum computers yet), I didn't think it applied to me. Anyways, maybe time to follow suit with the Jupyter setup :)

Thanks for your consideration!

[frankharkins]

That makes sense, I think we can do a couple of things:

1. Update the comment to be a bit clearer, here's a quick draft that could definitely be improved upon:

# Return a drawing of the circuit using MatPlotLib ("mpl"). These guides are
# written using Jupyter notebooks, which display the output of the last line
# of each cell. If you're running this in a script, use `print(qc.draw())` to
# print a text drawing.

2. Find a good place for an admonition explaining Jupyter notebooks and that these guides use them, either at the top of the page or near the first code cell.