More serverless tweaks

[abbycross]

cc: @acastellane

It appears that the original guide was written with the expectation that the user would download the notebook and run it end-to-end, but hidden code and magic commands don't appear in the published docs, which can be confusing to the user. Clarifying the content to explain this and to make sure the workflow makes sense whether it is run from the downloaded version, or from a copy-and-paste notebook.

[qiskit-bot]

One or more of the following people are relevant to this code:

• @jenglick
• @pandasa123
• @abbycross

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[acastellane]

Much better user experience at the beginning ! Thank you !

• I would recommend to move the cell containing the code:
  Path("./source_files").mkdir(exist_ok=True)
  after the "Create the directory" cell

• For some reason on my notebook the commented line preceding the magic command prevents it to operate.

# Each circuit is being transpiled and will populate the array
%%writefile --append ./source_files/transpile_remote.py

generates:
UsageError: Line magic function %%writefile not found.

• what prevents to provide the magic commands in the main text ? That would add consistency and simplify flow.
  If we can't, then the sentence: "a hidden cell will create the source_files directory" would better be "cells contain IPython magic commands to create or append the file of concern ..." or something like this as nothing is hidden ?
  And then the code should not be "executable" or "copied as a runnable code", since technically it is just raw text to be used in an editor. That will reduce misunderstanding risks for light readers.

• Here : https://qiskit.github.io/documentation/main/docs/guides/serverless-first-program#upload-to-qiskit-serverless
  I would remove
  "(which is demonstrated in the Run your first Qiskit Serverless workload remotely guide)." as it leads user's mind to a future that he can't run now.

• This following tips is too early and has its place in the run section (which is already the case)

TIP: Currently, the Workloads table on IBM Quantum Platform only reflects Qiskit Runtime workloads. To see the status of your Qiskit Serverless workloads, use job.status(). Find an example in the Run your first Qiskit Serverless workload remotely guide.

Thanks

[abbycross]

* I would recommend to move the cell containing the code:
  `Path("./source_files").mkdir(exist_ok=True)`
  after the "Create the directory" cell

done in f5d5d55

[abbycross]

This following tips is too early and has its place in the run section (which is already the case)

Removed in 89b577b

[abbycross]

Here : https://qiskit.github.io/documentation/main/docs/guides/serverless-first-program#upload-to-qiskit-serverless
I would remove
"(which is demonstrated in the Run your first Qiskit Serverless workload remotely guide)." as it leads user's mind to a future that he can't run now.

I had already removed this - just in case you're seeing an old version, be sure you're using this as the preview url: https://qiskit.github.io/documentation/pr-4715/docs/guides/serverless-first-program

[abbycross]

For some reason on my notebook the commented line preceding the magic command prevents it to operate.
.
.
.
what prevents to provide the magic commands in the main text ? That would add consistency and simplify flow.
If we can't, then the sentence: "a hidden cell will create the source_files directory" would better be "cells contain IPython magic commands to create or append the file of concern ..." or something like this as nothing is hidden ?
And then the code should not be "executable" or "copied as a runnable code", since technically it is just raw text to be used in an editor. That will reduce misunderstanding risks for light readers.

Turns out the magic commands only work when they are at the very top of a cell.

In conversation with @frankharkins I got some history on the inclusion of magic commands in this file. When it was added, it was to make the notebook testable in our CI, and the expectation wasn't that the user would download and run the file start-to-end. Given the new confusion, Frank recommends that we remove them and instead put in regular Python that users can run end-to-end, AND be testable by our CI. We would reword a bit to make sure it's clear what the user is supposed to do.

[frankharkins]

@acastellane here's some more context on the %%writefile magic and associated feature:

In #1861, we decided on a feature to indicate that code cells are referring to the contents of separate files. We implemented this by detecting the %%writefile magic and displaying a banner above the code cell with the file name. The banner makes it clear on the website that the code belongs in a separate file and should not be executed in the normal flow of the page, and the %%writefile magic saves these cells to the specified files during notebook execution so that we can test the notebook works.

However, I understand it could be confusing if a user downloads the notebook and has never seen a Jupyter magic before.

In #4793, I tried removing the magics and replacing them with standard Python, but I think this worsens the experience for most users as it's harder to read and removes syntax highlighting in the source program. (See preview).

As an alternative, I created #4794, which instead adds an explanation for users reading/running the notebook locally (preview). I think this is a better solution; do you think this resolves the confusion?

---

For some reason on my notebook the commented line preceding the magic command prevents it to operate.

FYI this is expected, see https://ipython.readthedocs.io/en/9.2.0/interactive/magics.html#cell-magics
You can fix it by moving the comment after the magic.