Add Migration Guide for Opflow

[ElePT]

Summary

This PR closes #9484
Blocked by #9716 (doctest & intersphinx config) Copied over docs config from #9716 (agreed upon with @HuangJunye)

Details and comments

Open Questions:

• Should I remove the links to the opflow API ref?
• Any formatting improvements?
• Any examples that you miss?

TO-DOs:

• Add StateFn and expectations examples
• Add links for gradient section (tutorial still not created)
• Add hyperlinks to other sections when mentioned (see ... example type of references)
• Make explanation for evolutions more concise

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

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

• @Cryoris
• @Qiskit/terra-core
• @manoelmarques
• @woodsp-ibm

[coveralls]

Pull Request Test Coverage Report for Build 4617374131

• 3 of 3 (100.0%) changed or added relevant lines in 3 files are covered.
• 5 unchanged lines in 3 files lost coverage.
• Overall coverage decreased (-0.03%) to 85.401%

---

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/vf2_layout.rs	1	86.44%
qiskit/circuit/tools/pi_check.py	1	91.23%
qiskit/pulse/library/waveform.py	3	91.67%

Totals
Change from base Build 4617156725:	-0.03%
Covered Lines:	67458
Relevant Lines:	78990

---

💛 - Coveralls

[ikkoham]

Thank you for great work! I left some comments.

[woodsp-ibm]

I think Matthew said someway about running/testing these samples. Note sure if thats doctest - we have used that in apps. (Reason I comment here is due to typo in import - PuliSumOp no a

[ElePT]

@mtreinish?

[Cryoris]

I'm pretty sure these are not tested at the moment, unless they are in a jupyter-execute environment 🙂

[ElePT]

So @woodsp-ibm, I managed to find an inbetween solution, I formatted the code examples to be runnable locally with pytest's doctest. I don't know if I like having all of the >>> in the code, but at least we can make sure that it runs.

[woodsp-ibm]

It is also possible to use ..testcode:: and ..testoutput:: directives (they are supported by the sphinx.ext.doctest, which we use in the apps and imagine would be used here too). By default the output puts these in separate highlighted blocks (though you can hide the testoutput if desired) but there is no need for >>> when using these.

I know though we used >>> in Nature etc since formatting with these former seemed harder to get things to come out right/as wanted etc. The >>> was always more concise and seemed easier to add and have it come out as expected in among other text. Maybe there is styling that can applied to testcode/output so things can be improved, not sure.

E.g.

.. testcode::

    x = 1 + 3
    print(x)

.. testoutput::

    4

comes out as

[woodsp-ibm]

Should I remove the links to the opflow API ref?

If this is published along with the API ref and by kept version, as the docs currently are, then this migration guide could be removed when opflow is removed. If not then afterwards the class refs will just be highlighted - just not links since they would not resolve. To me having them as class refs so they can be links seems better - since as links I can go to the opflow class itself for more detail if I need that.

[HuangJunye]

LGTM. Thanks a lot for working on this!

[Cryoris]

LGTM -- only one more left! 😄