Update docs build (#1406)

### Summary

- Removes the developmental banner from the production docs build
- Updates docs builds to use Python 3.12
- Adds `pyarrow` to developmental requirements to avoid `pandas` warning
during docs build
- Updates analysis results docs in Getting Started to warn against
numerical indices

.github/workflows/cron-staging.yml

@@ -53,10 +53,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
       - name: Pip cache
         uses: actions/cache@v4
         with:

.github/workflows/docs_dev.yml

@@ -15,7 +15,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.8'
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/docs_release.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.8'
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -25,7 +25,7 @@ jobs:
     - name: Build docs
       env:
         QISKIT_DOCS_BUILD_TUTORIALS: 'always'
-      run: EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 tox -edocs
+      run: PROD_BUILD=1 tox -edocs
     - name: Bypass Jekyll Processing # Necessary for setting the correct css path
       run: touch docs/_build/html/.nojekyll
     - name: Deploy

.github/workflows/docs_stable.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.8'
+          python-version: '3.12'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip

.github/workflows/main.yml

@@ -88,10 +88,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Set up Python 3.8
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: 3.12
       - name: Pip cache
         uses: actions/cache@v4
         with:

docs/tutorials/getting_started.rst

@@ -185,23 +185,36 @@ exponential decay model of the :math:`T_1` experiment:
 Analysis Results
 ----------------
 
-The analysis results resulting from the fit are accessed with :meth:`~.ExperimentData.analysis_results`:
+The analysis results resulting from the fit are accessed with
+:meth:`~.ExperimentData.analysis_results`. If the ``dataframe=True`` parameter is passed, analysis
+results will be retrieved in the pandas :class:`~pandas:pandas.DataFrame` format:
+
+.. jupyter-execute::
+
+    exp_data.analysis_results(dataframe=True)
+
+Alternatively, analysis results can be accessed via the legacy list format:
 
 .. jupyter-execute::
 
     for result in exp_data.analysis_results():
         print(result)
 
-Results can be indexed numerically (starting from 0) or using their name. Analysis results can also be
-retrieved in the pandas :class:`~pandas:pandas.DataFrame` format by passing ``dataframe=True``:
+Individual results can be retrieved using their name or their long or short IDs, which will all
+return the corresponding :class:`AnalysisResult` object:
 
 .. jupyter-execute::
+    :hide-code:
 
-    exp_data.analysis_results(dataframe=True)
+    result_id = exp_data.analysis_results("T1").result_id
+    short_id = result_id.split("-")[0]
+    print(f"exp_data.analysis_results(\"T1\")")
+    print(f"exp_data.analysis_results(\"{result_id}\")")
+    print(f"exp_data.analysis_results(\"{short_id}\")")
 
-.. note::
-    See the :meth:`~.ExperimentData.analysis_results` API documentation for more 
-    advanced usage patterns to access subsets of analysis results.
+.. attention::
+    Retrieving analysis results by a numerical index, whether an integer or a slice, is deprecated
+    as of 0.6 and will be removed in a future release.
 
 Each analysis
 result value is a ``UFloat`` object from the ``uncertainties`` package. The nominal

qiskit_experiments/framework/experiment_data.py

@@ -1475,6 +1475,11 @@ def analysis_results(
     ) -> AnalysisResult | list[AnalysisResult] | pd.DataFrame:
         """Return analysis results associated with this experiment.
 
+        .. caution::
+            Retrieving analysis results by a numerical index, whether an integer or a slice,
+            is deprecated as of 0.6 and will be removed in a future release. Use the name
+            or ID of the result instead.
+
         When this method is called with ``dataframe=True`` you will receive
         matched result entries with the ``index`` condition in the dataframe format.
         You can access a certain entry value by specifying its row index by either

tox.ini

@@ -69,6 +69,9 @@ passenv =
   PROD_BUILD
   RELEASE_STRING
   VERSION_STRING
+deps =
+  {[testenv]deps}
+  pyarrow
 commands =
   sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
@@ -79,6 +82,9 @@ passenv =
   PROD_BUILD
   RELEASE_STRING
   VERSION_STRING
+deps =
+  {[testenv]deps}
+  pyarrow
 commands =
   sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
@@ -89,6 +95,9 @@ passenv =
   PROD_BUILD
   RELEASE_STRING
   VERSION_STRING
+deps =
+  {[testenv]deps}
+  pyarrow
 setenv = 
   QISKIT_DOCS_SKIP_EXECUTE = 1
 commands =
@@ -104,6 +113,7 @@ passenv =
 deps =
   {[testenv]deps}
   git+https://github.com/Qiskit/qiskit
+  pyarrow
 commands =
   sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html