Remove metapackage-specific parts of documentation (Qiskit/qiskit-met…

…apackage#1788)

This removes many sections of the documentation that refer to the
metapackage as a whole, the elements of the metapackage, or refer to
Terra as Terra. This is intended to be in line with the new branding
decisions around the Qiskit project.

With the current community management structure still a little up in the
air, we are (at least temporarily) removing the repository-decision
flowchart from the documentation, since this documentation will
primarily be for Qiskit Terra. The contributor flowchart, or something
similar, may end up on the landing pages of the Ecosystem documentation,
or another community hub.


I've left references to "Terra" in place, because those should still
logically be removed as part of the general migration in naming within
the Terra repository. I've also left the build processes in place that
`git clone` Terra and the tutorials; we need those to continue having a
working docs build in this repo. They'll get modified as these files get
merge to Terra as well, but they need to stay alive here.

One of the notable removals is the API docs links to Aer and IBMQ from
the main page, since as of the deployed metapackage version (0.44),
those are no longer part of the metapackage.

Fix Qiskit/qiskit-metapackage#1787.
Fix Qiskit/qiskit-metapackage#1778 - mostly; the version logic is _way_ stripped down, and will
now automatically work on Terra at least as much as we need when the
files are merged.
Fix Qiskit/qiskit-metapackage#1667 
Fix Qiskit/qiskit-metapackage#1643

docs/conf.py

@@ -25,7 +25,6 @@
 sys.path.insert(0, os.path.abspath("."))
 
 import custom_extensions
-import versionutils
 
 # -- General configuration ---------------------------------------------------
 
@@ -213,5 +212,5 @@
 def setup(app):
     custom_extensions.load_terra_docs(app)
     custom_extensions.load_tutorials(app)
-    versionutils.setup(app)
+    app.connect("config-inited", custom_extensions.add_versions_to_config)
     app.connect("build-finished", custom_extensions.clean_docs)

docs/configuration.rst

@@ -79,12 +79,12 @@ behavior of Qiskit.
    the use of
    `Python multiprocessing <https://docs.python.org/3/library/multiprocessing.html>`__
    to parallelize certain operations (for example transpilation over multiple
-   circuits) in Qiskit Terra.
+   circuits) in Qiskit.
  * ``QISKIT_NUM_PROCS``: Specifies the maximum number of parallel processes to
    launch for parallel operations if parallel execution is enabled. It takes an
    integer > 0 as the expected value.
  * ``RAYON_NUM_THREADS``: Specifies the number of threads to run multithreaded
-   operations in Qiskit Terra. By default this multithreaded code will launch
+   operations in Qiskit. By default this multithreaded code will launch
    a thread for each logical CPU, if you'd like to adjust the number of threads
    Qiskit will use you can set this to an integer value. For example, setting
    ``RAYON_NUM_THREADS=4`` will only launch 4 threads for multithreaded
@@ -96,16 +96,3 @@ behavior of Qiskit.
    This is done to avoid potentially overloading limited CPU resources. However,
    if you would like to force the use of multiple threads even when in a
    multiprocess context you can set ``QISKIT_FORCE_THREADS=TRUE`` to do this.
- * ``QISKIT_IBMQ_PROVIDER_LOG_LEVEL``: Specifies the log level to use, for the
-   ``qiskit-ibmq-provider`` modules. If an invalid level is set, the log level
-   defaults to WARNING. The valid log levels are ``DEBUG``, ``INFO``,
-   ``WARNING``, ``ERROR``, and ``CRITICAL`` (case-insensitive). If the
-   environment variable is not set, then the parent logger’s level is used,
-   which also defaults to ``WARNING``.
- * ``QISKIT_IBMQ_PROVIDER_LOG_FILE``: Specifies the name of the log file to
-   use from log messages originating from ``qiskit-ibmq-provider``. If
-   specified, messages will be logged to the file only. Otherwise messages will
-   be logged to the standard error (usually the screen).
- * ``QISKIT_AQUA_MAX_GATES_PER_JOB``: An optional parameter to set a threshold
-   for splitting Aqua generated circuits up into multiple jobs submitted to a
-   backend based on the number of gates.

docs/contributing_to_qiskit.rst

@@ -13,24 +13,11 @@ Before You Start
 If you are new to Qiskit contributing we recommend you do the following before diving into the code:
 
 #. Read the `Code of Conduct <https://github.com/Qiskit/qiskit/blob/master/CODE_OF_CONDUCT.md>`__
-#. :ref:`Decide what to work on <decide-what-to-work-on>`
 #. Read the repo-specific :ref:`Contributing Guidelines <contributing_links>` for the repo you have decided to contribute to.
 #. :ref:`Set up your development environment <dev-env-setup>`
 #. Familiarize yourself with the Qiskit community (via `Slack <https://qisk.it/join-slack>`__,
    `Stack Exchange <https://quantumcomputing.stackexchange.com/>`__, `GitHub <https://github.com/qiskit-community/feedback/discussions>`__ etc.)
 
-
-.. _decide-what-to-work-on:
-
-************************
-Decide What to Work on
-************************
-
-If you're not sure what type of contribution is right for you, take a look at the following flowchart to help you:
-
-.. raw:: html
-   :file: images/contributor-flowchart.svg
-
 .. _contributing_links:
 
 ********************************

docs/custom_extensions.py

@@ -17,6 +17,10 @@
 import warnings
 from pathlib import Path
 
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
 TERRA_FILES = []
 TERRA_DIRS = [
     "apidoc",
@@ -74,6 +78,27 @@ def load_tutorials(app):
             shutil.copytree(Path(temp_dir, "tutorials", d), Path(app.srcdir, "tutorials", d))
 
 
+def add_versions_to_config(_app, config):
+    """Add a list of old documentation versions that should have links generated to them into the
+    context, so the theme can use them to generate a sidebar."""
+    # First 0.x version where Qiskit/Terra and the metapackage aligned on number.
+    first_unified_zero_minor = 45
+
+    # Start with the hardcoded versions of the documentation that were managed while the metapackage
+    # still existed, so are based on tags that don't exist in the Qiskit package repo.
+    versions = ["0.19"] + [f"0.{x}" for x in range(24, first_unified_zero_minor)]
+
+    proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True, check=True)
+    current_version = proc.stdout.decode("utf8")
+    current_version_info = current_version.split(".")
+    if current_version_info[0] != "0":
+        raise Exception("TODO: handle major versions")
+    versions.extend(
+        f"0.{x}" % x for x in range(first_unified_zero_minor, int(current_version_info[1]) + 1)
+    )
+    config.html_context["version_list"] = versions
+
+
 def clean_docs(app, exc):
     """Deletes the Git cloned docs."""
     for d in [*TERRA_DIRS, "tutorials"]:

docs/deprecation_policy.rst

@@ -143,7 +143,7 @@ Usually, you should set ``additional_msg: str `` with the format ``"Instead, use
 people know how to migrate. Read those functions' docstrings for additional arguments like
 ``pending: bool`` and ``predicate``.
 
-If you are deprecating in a non-Terra repo, set ``package_name``, e.g. to ``qiskit-nature``.
+If you are deprecating outside the main Qiskit repo, set ``package_name`` to match your package.
 Alternatively, if you prefer to use your own decorator helpers, then have them call
 ``add_deprecation_to_docstring`` from ``qiskit.utils.deprecation``.