Skip to content
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.

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

Rework QPY docs #10310

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Rework QPY docs #10310

wants to merge 6 commits into from

Conversation

ElePT
Copy link
Contributor

@ElePT ElePT commented Jun 19, 2023

Summary

Attempts to fix/improve #9967.

Details and comments

The QPY doc used to incrementally "build up" with every QPY release in a way that made it hard to get an overview of what the format looks like now. In this PR, I try to improve the readability fixing this issue and adding a few more changes, namely:

  1. "squashed" all versions from the previous doc into a single overview, while still providing some context of when were certain elements added to the format
  2. added a "version history" table that allows people to see in which terra release was QPY bumped to which version. This is to compensate for the loss of historical tracking in the doc, people can always inspect the releasenotes or release artifacts and see what the code looked like then (note, I have double checked a couple of times, and still concluded that QPY v.3 and v.4 were both part of the same release. Correct me if I'm wrong)
  3. added more headers, structure to the text, and where possible tried to add a schematic overview of what each block looks like (HEADER | DATA | ...)
  4. reviewed grammar, spelling, tried to unify notation

Note: The local build/CI does not show document headings after a certain level ( the ones with ------- or ==== are not shown) in the sidebar menu, but the current deployed docs do show them, at least until (----). I am assuming there is some difference in the Sphinx theme that doesn't show them.

@mtreinish mtreinish self-assigned this Jun 19, 2023
@coveralls
Copy link

coveralls commented Jun 19, 2023

Pull Request Test Coverage Report for Build 5336201879

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • 229 unchanged lines in 6 files lost coverage.
  • Overall coverage decreased (-0.03%) to 85.93%

Files with Coverage Reduction New Missed Lines %
qiskit/extensions/quantum_initializer/initializer.py 1 97.3%
crates/qasm2/src/lex.rs 3 90.63%
qiskit/circuit/library/data_preparation/state_preparation.py 7 96.35%
crates/qasm2/src/parse.rs 12 96.65%
qiskit/dagcircuit/dagcircuit.py 21 89.64%
qiskit/visualization/circuit/matplotlib.py 185 57.41%
Totals Coverage Status
Change from base Build 5313232499: -0.03%
Covered Lines: 71276
Relevant Lines: 82947

💛 - Coveralls

Copy link
Member

@mtreinish mtreinish left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've only done a quick high level skim over this so far. At a high level this reorganization is a huge improvement over the structure we had in the format docs before. Thanks for doing this!

What was missing before was the top overview of the current format. The historical artifacts are important for anyone potentially writing a deserializer for backwards compatibility. But for people trying to figure out how the format works and what terra is emitting today we had the order of everything backwards.

The one thing I also wanted to call out is that this will have a conflict with #10148 which is adding version 8. I wrote the docs there in the existing format. But we can handle the conflict based on what merges first I guess.

Comment on lines 164 to 165
- When ``type==c``, :class:`~.QuantumCircuit` payloads follow
- When ``type==s``, :class:`~.ScheduleBlock` payloads follow
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe link to the section too here. For circuit it's easy because it's right below. But for schedule block it's a lot of scrolling :)

@ElePT ElePT marked this pull request as ready for review June 21, 2023 15:31
@ElePT ElePT requested a review from a team as a code owner June 21, 2023 15:31
@qiskit-bot
Copy link
Collaborator

One or more of the the following people are requested to review this:

  • @Qiskit/terra-core
  • @mtreinish
  • @nkanazawa1989

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants