Add Migration Guide for qiskit.algorithms (Qiskit#9557)

* Add draft

* Remove qiskit

* Apply review

* Add algos guide

* Add skeleton

* Add content

* Fix sampling VQE example

* Apply suggestions from Steve's code review

Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>

* Apply review, update code examples up to Eigensolvers

* Add doctest to sphinx config

* Add tests up to eigensolvers

* Review code examples from Eigensolvers

* Update heading style

* Apply suggestions from Declan's code review

Co-authored-by: Declan Millar <declan.millar@ibm.com>

* Apply suggestions from Steve's code review

Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>

* Apply review

* Final changes, fix docs

* Apply Julien's comments

---------

Co-authored-by: Steve Wood <40241007+woodsp-ibm@users.noreply.github.com>
Co-authored-by: Declan Millar <declan.millar@ibm.com>

docs/conf.py

@@ -16,6 +16,7 @@
 
 # -- General configuration ---------------------------------------------------
 import datetime
+import doctest
 
 project = "Qiskit"
 copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
@@ -37,7 +38,9 @@
     "reno.sphinxext",
     "sphinx_design",
     "matplotlib.sphinxext.plot_directive",
+    "sphinx.ext.doctest"
 ]
+
 templates_path = ["_templates"]
 
 # Number figures, tables and code-blocks if they have a caption.
@@ -62,6 +65,7 @@
 
 intersphinx_mapping = {
     "retworkx": ("https://qiskit.org/documentation/retworkx/", None),
+    "qiskit_ibm_runtime": ("https://qiskit.org/documentation/partners/qiskit_ibm_runtime/", None)
 }
 
 # -- Options for HTML output -------------------------------------------------
@@ -108,3 +112,7 @@
 }
 
 autoclass_content = "both"
+
+# -- Options for doctest -------------------------------------
+
+doctest_default_flags = doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE | doctest.IGNORE_EXCEPTION_DETAIL | doctest.DONT_ACCEPT_TRUE_FOR_1

docs/index.rst

@@ -8,7 +8,8 @@ Qiskit Terra documentation
 
   API References <apidocs/terra>
   Release Notes <release_notes>
-
+  Migration Guides <migration_guides/index>
+
 .. Hiding - Indices and tables
    :ref:`genindex`
    :ref:`modindex`