Show more sample output with primitives

[Eric-Arellano]

Feedback

It's useful to see the output of primitives code to understand how they behave. We don't show this in https://docs.quantum.ibm.com/run/primitives-get-started, https://docs.quantum.ibm.com/run/primitives, https://docs.quantum.ibm.com/run/primitives-examples. We only have print statements that aren't executed.

Other comments

This could be somewhat addressed by rewriting the files to Jupyter notebooks that show the output: #169.

[beckykd]

the difficulty with converting these to notebooks is that they show V1 vs V2 and we haven't figured out how to nicely do that in notebooks. But I can add output

[abbycross]

Jumping in, since I just went through the process of converting an mdx file with tabs in it, to ipynb.

For the uninitiated, tab syntax is like this:

<Tabs>
<TabItem value="value1" label="label1">
</TabItem>
<TabItem value="value2" label="label2">
</TabItem>
</Tabs>

If there were a way to include two types of code cells within each TabItem, there would be no problem. We generally need at least one markdown cell and at least one code cell for each tab.

Since (so far) it seems we can't do that, both the markdown and the code must be enclosed within one markdown cell, which means the code cannot get checked by the linter.

It also renders difficult the ability to display the output of the code, since it has to be manually placed, rather than simply running the code and including the output from that.

Hoping some other, better solutions will bubble up :)

[beckykd]

Jumping in, since I just went through the process of converting an mdx file with tabs in it, to ipynb.

For the uninitiated, tab syntax is like this:

<Tabs> <TabItem value="value1" label="label1"> </TabItem> <TabItem value="value2" label="label2"> </TabItem> </Tabs>

If there were a way to include two types of code cells within each TabItem, there would be no problem. We generally need at least one markdown cell and at least one code cell for each tab.

Since (so far) it seems we can't do that, both the markdown and the code must be enclosed within one markdown cell, which means the code cannot get checked by the linter.

It also renders difficult the ability to display the output of the code, since it has to be manually placed, rather than simply running the code and including the output from that.

Hoping some other, better solutions will bubble up :)

This is why I haven't converted any. :)

[ElePT]

I have noticed the issues with converting tabs in jupyter notebooks while reviewing #812. I think that the tabs are really valuable when showing side-by-side V1 and V2 code, and as far as I know, there isn't a good alternative in jupyter notebooks (other than duplicating the notebook and having a V1 and V2 version, which I personally wouldn't mind as a user, but might be complicated to handle in terms of links etc). In general, I think that jupyter offers less flexibility in terms of formatting options.

When we were using sphinx to render the docs we could add testeable snippets to the .rst file using doctest, I wonder if finding a similar feature for the current format could help not to have to migrate all the content to notebooks? (edit: if linting doesn't catch what's inside the tabs, the code testing might not catch it either, so maybe this suggestion isn't the way to go)

[beckykd]

run/primitives.mdx doesn't have any print statements.

[frankharkins]

You can actually wrap notebook cells in tab blocks. Just end a markdown cell with <Tabs><TabItem value="value1" label="label1"> (plus any markdown content you want in the tab), then add your code cell, then start the next markdown cell with </TabItem><TabItem value="value2" label="label2"> etc.

It's not perfect (from an editing standpoint) but worked OK for me in docs/build-new/plot-quantum-states.ipynb.