Create new documentation page

.github/workflows/deploy-docs.yml

@@ -0,0 +1,52 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+name: Deploy Docs
+
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.repository }}-${{ github.ref }}-${{ github.head_ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  docs_publish:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -U virtualenv setuptools wheel tox
+          sudo apt-get install -y graphviz pandoc
+        shell: bash
+      - name: Build and publish
+        env:
+          encrypted_rclone_key: ${{ secrets.encrypted_rclone_key }}
+          encrypted_rclone_iv: ${{ secrets.encrypted_rclone_iv }}
+          QISKIT_PARALLEL: False
+          QISKIT_DOCS_BUILD_TUTORIALS: 'always'
+        run: |
+          tools/deploy_documentation.sh
+        shell: bash

.github/workflows/main.yml

@@ -47,7 +47,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -U 'tox<4'
-          sudo apt install -y graphviz
+          sudo apt install -y graphviz pandoc
           pip install -c constraints.txt -e .
       - name: Build docs
         run: tox -edocs

.github/workflows/pr.yml

@@ -76,7 +76,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -U 'tox<4'
-          sudo apt install -y graphviz
+          sudo apt install -y graphviz pandoc
           pip install -c constraints.txt -e .
       - name: Build docs
         run: tox -edocs

.gitignore

@@ -106,3 +106,4 @@ Qconfig.py
 .DS_Store
 
 /docs/stubs/
+/docs/.doctrees/

docs/conf.py

@@ -25,22 +25,23 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+import datetime
+sys.path.insert(0, os.path.abspath('.'))
 
 """
 Sphinx documentation builder
 """
 
-import os
 # Set env flag so that we can doc functions that may otherwise not be loaded
 # see for example interactive visualizations in qiskit.visualization.
 os.environ['QISKIT_DOCS'] = 'TRUE'
 
 # -- Project information -----------------------------------------------------
+
 project = 'Qiskit IBM Q Provider'
-copyright = '2019, Qiskit Development Team'  # pylint: disable=redefined-builtin
+copyright = f'2019-{datetime.date.today().year}, Qiskit Development Team'  # pylint: disable=redefined-builtin
 author = 'Qiskit Development Team'
 
 # The short X.Y version
@@ -68,13 +69,36 @@
     'jupyter_sphinx',
     'sphinx_autodoc_typehints',
     'reno.sphinxext',
+    "sphinxcontrib.jquery",  # Remove when changing html_theme to qiskit_ecosystem.
+    'nbsphinx'
 ]
 html_static_path = ['_static']
 templates_path = ['_templates']
 html_css_files = [
     'style.css',
 ]
 
+nbsphinx_timeout = 300
+nbsphinx_execute = os.getenv('QISKIT_DOCS_BUILD_TUTORIALS', 'never')
+nbsphinx_widgets_path = ''
+
+nbsphinx_prolog = """
+{% set docname = env.doc2path(env.docname, base=None) %}
+.. only:: html
+
+    .. role:: raw-html(raw)
+        :format: html
+
+    .. note::
+        This page was generated from `docs/{{ docname }}`__.
+
+        __"""
+
+
+vers = release.split(".")
+link_str = f" https://github.com/Qiskit/qiskit-ibmq-provider/blob/stable/{vers[0]}.{vers[1]}/docs/"
+nbsphinx_prolog += link_str + "{{ docname }}"
+
 # -----------------------------------------------------------------------------
 # Autosummary
 # -----------------------------------------------------------------------------
@@ -111,7 +135,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'colorful'
@@ -136,7 +160,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'  # use the theme in subdir 'theme'
+html_theme = 'qiskit_sphinx_theme'
 
 html_logo = 'images/logo.png'
 #html_sidebars = {'**': ['globaltoc.html']}
@@ -147,12 +171,11 @@
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': True,
-    'style_nav_header_background': '#212121',
 }
 
 rst_prolog = """.. warning::
    The package ``qiskit-ibmq-provider`` is being deprecated and its repo is going to be archived soon.
    Please transition to the new packages. More information in https://ibm.biz/provider_migration_guide
 """
 
-autoclass_content = 'both'
+autoclass_content = 'both'

docs/index.rst

@@ -3,10 +3,13 @@ Qiskit IBM Quantum Provider documentation
 #########################################
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 1
 
+  Documentation Home <self>
+  Tutorials <tutorials/index>
   API References <apidocs/ibmq-provider>
   Release Notes <release_notes>
+  GitHub <https://github.com/Qiskit/qiskit-ibmq-provider>
 
 .. Hiding - Indices and tables
    :ref:`genindex`

docs/tutorials/index.rst

@@ -0,0 +1,9 @@
+#############################
+Qiskit IBM Provider Tutorials
+#############################
+
+
+.. nbgallery::
+
+   1_the_ibmq_account
+   2_jupyter_tools

releasenotes/config.yaml

@@ -0,0 +1,3 @@
+---
+encoding: utf8
+default_branch: master

requirements-dev.txt

@@ -4,7 +4,7 @@ pylint==2.4.4
 vcrpy
 pproxy==2.1.8
 Sphinx>=1.8.3
-sphinx-rtd-theme>=0.4.0
+qiskit_sphinx_theme~=1.11.1
 sphinx-tabs>=1.1.11
 sphinx-automodapi
 sphinx-autodoc-typehints
@@ -20,6 +20,7 @@ pyperclip>=1.7
 jupyter-sphinx
 reno>=2.11.0
 scipy>=1.0
+nbsphinx
 nbformat>=4.4.0
 nbconvert>=5.3.1
 qiskit_rng

tools/deploy_documentation.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# Script for pushing the documentation to qiskit.org/ecosystem.
+set -e
+
+curl https://downloads.rclone.org/rclone-current-linux-amd64.deb -o rclone.deb
+sudo apt-get install -y ./rclone.deb
+
+RCLONE_CONFIG_PATH=$(rclone config file | tail -1)
+
+# Build the documentation.
+tox -edocs
+
+echo "show current dir: "
+pwd
+
+# Push to qiskit.org/ecosystem
+openssl aes-256-cbc -K $encrypted_rclone_key -iv $encrypted_rclone_iv -in tools/rclone.conf.enc -out $RCLONE_CONFIG_PATH -d
+echo "Pushing built docs to qiskit.org/ecosystem"
+rclone sync --progress ./docs/_build/html IBMCOS:qiskit-org-web-resources/ecosystem/ibmq-provider

tox.ini

@@ -39,7 +39,7 @@ deps =
   qiskit-aer
 commands =
   pip install -c{toxinidir}/constraints.txt -U -r requirements-dev.txt
-  sphinx-build -W -b html {posargs} {toxinidir}/docs {toxinidir}/docs/_build/html
+  sphinx-build -W -b html {posargs} {toxinidir}/docs {toxinidir}/docs/_build/html -d {toxinidir}/docs/.doctrees
 
 [testenv:gettext]
 envdir = .tox/docs
@@ -48,7 +48,7 @@ deps =
   -r requirements-dev.txt
   qiskit-aer
 commands =
-  sphinx-build -W -b gettext docs/ docs/_build/gettext {posargs}
+  sphinx-build -W -b gettext {toxinidir}/docs/ {toxinidir}/docs/_build/gettext {posargs}
 
 [doc8]
 max-line-length=100