From 48656b388edbb1b3ea8ab900b3670ffa43058eed Mon Sep 17 00:00:00 2001
From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Date: Mon, 5 Jun 2023 11:17:27 -0600
Subject: [PATCH] Upgrade to qiskit_sphinx_theme 1.12 (#1822)

---
 .github/workflows/docs-publish.yml |  1 +
 docs/conf.py                       | 16 ++-----
 docs/custom_directives.py          | 68 ------------------------------
 docs/getting_started.rst           |  2 +-
 requirements-dev.txt               |  2 +-
 tox.ini                            |  6 +++
 6 files changed, 12 insertions(+), 83 deletions(-)
 delete mode 100644 docs/custom_directives.py

diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml
index 4cdb823bfb..6c5ffaae34 100644
--- a/.github/workflows/docs-publish.yml
+++ b/.github/workflows/docs-publish.yml
@@ -1,5 +1,6 @@
 name: Docs Publish
 on:
+  workflow_dispatch:
   push:
     tags:
       - "*"
diff --git a/docs/conf.py b/docs/conf.py
index aa141d2990..0d50ec591d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,9 +25,9 @@
 # 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
+# sys.path.insert(0, os.path.abspath('.'))
 
 """
 Sphinx documentation builder
@@ -38,18 +38,12 @@
 # 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'
-sys.path.insert(0, os.path.abspath('.'))
 
 # -- Project information -----------------------------------------------------
 project = 'Qiskit Aer'
 copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"  # pylint: disable=redefined-builtin
 author = 'Qiskit Development Team'
 
-import qiskit_sphinx_theme
-from custom_directives import (
-    CustomCalloutItemDirective
-)
-
 # The short X.Y version
 version = '0.12.1'
 # The full version, including alpha/beta/rc tags
@@ -162,7 +156,3 @@
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "qiskit": ("https://qiskit.org/documentation/", None),
 }
-
-# -- Extension configuration -------------------------------------------------
-def setup(app):
-    app.add_directive("customcalloutitem", CustomCalloutItemDirective)
diff --git a/docs/custom_directives.py b/docs/custom_directives.py
deleted file mode 100644
index 2c5ae28cec..0000000000
--- a/docs/custom_directives.py
+++ /dev/null
@@ -1,68 +0,0 @@
-from docutils.parsers.rst import Directive, directives
-from docutils.statemachine import StringList
-from docutils import nodes
-
-try:
-    FileNotFoundError
-except NameError:
-    FileNotFoundError = IOError
-
-
-class CustomCalloutItemDirective(Directive):
-    option_spec = {
-        "header": directives.unchanged,
-        "description": directives.unchanged,
-        "button_link": directives.unchanged,
-        "button_text": directives.unchanged,
-    }
-
-    def run(self):
-        try:
-            if "description" in self.options:
-                description = self.options["description"]
-            else:
-                description = ""
-
-            if "header" in self.options:
-                header = self.options["header"]
-            else:
-                raise ValueError("header not doc found")
-
-            if "button_link" in self.options:
-                button_link = self.options["button_link"]
-            else:
-                button_link = ""
-
-            if "button_text" in self.options:
-                button_text = self.options["button_text"]
-            else:
-                button_text = ""
-
-        except FileNotFoundError as e:
-            print(e)
-            return []
-        except ValueError as e:
-            print(e)
-            raise
-            return []
-
-        callout_rst = CALLOUT_TEMPLATE.format(
-            description=description, header=header, button_link=button_link, button_text=button_text
-        )
-        callout_list = StringList(callout_rst.split("\n"))
-        callout = nodes.paragraph()
-        self.state.nested_parse(callout_list, self.content_offset, callout)
-        return [callout]
-
-
-CALLOUT_TEMPLATE = """
-.. raw:: html
-
-    <div class="col-md-6">
-        <div class="text-container">
-            <h3>{header}</h3>
-            <p class="body-paragraph">{description}</p>
-            <a class="btn with-right-arrow callout-button" href="{button_link}">{button_text}</a>
-        </div>
-    </div>
-"""
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index 9c653bb443..725260c52e 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -193,7 +193,7 @@ Ready to get going?...
    <div class="tutorials-callout-container">
       <div class="row">
 
-.. customcalloutitem::
+.. qiskit-call-to-action-item::
    :description: Find out about Qiskit Aer
    :header: Dive into the tutorials
    :button_link:  ./tutorials/index.html
diff --git a/requirements-dev.txt b/requirements-dev.txt
index d76df36c92..7e21763be6 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -13,6 +13,6 @@ reno>=3.4.0
 ddt>=1.2.0,!=1.4.0
 matplotlib>=3.3
 seaborn>=0.9.0
-qiskit_sphinx_theme>=1.10
+qiskit_sphinx_theme~=1.12.0
 sphinx-design>=0.2.0
 nbsphinx
diff --git a/tox.ini b/tox.ini
index 5e42476b4d..8f418f383c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -54,3 +54,9 @@ commands =
   python -I -m build --wheel -C=--build-option=-- -C=--build-option=-- -C=--build-option=-j4
   pip install --find-links={toxinidir}/dist qiskit_aer
   sphinx-build -W -b html docs/ docs/_build/html -j auto {posargs}
+
+[testenv:docs-clean]
+skip_install = true
+deps =
+allowlist_externals = rm
+commands = rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build