Add qiskit-card-item and qiskit-call-to-action-item directives

README.md

@@ -152,6 +152,15 @@ translations_list = [
 content_prefix = "ecosystem/finance"
 ```
 
+## Use custom RST directives
+
+The `qiskit_sphinx_theme` extension defines the below custom directives for you to use in RST, if you'd like. See `example_docs/docs/sphinx_guide/custom_directives.rst` for examples of how to use them.
+
+* `qiskit-card-item`
+* `qiskit-call-to-action-item`
+
+![Screenshot of examples of custom directives](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/9c672417-6451-4547-bc36-10709f7f3880)
+
 ## Enable Qiskit.org Analytics
 
 Qiskit.org uses Segment Analytics to collect information on traffic to sites under the qiskit.org domain. This is not enabled by default but if you would like to enable it you can add a `analytics_enabled` variable to the `html_context` object in your `conf.py`. Setting this to `True` will enable analytics for your site once it is deployed to `qiskit.org/documentation`. 

example_docs/docs/index.rst

@@ -28,5 +28,6 @@ Qiskit sphinx theme |version| documentation
    sphinx_guide/paragraph
    sphinx_guide/structural
    sphinx_guide/notebook_gallery
+   sphinx_guide/custom_directives
    sphinx_guide/long_title
    GitHub <https://github.com/Qiskit/qiskit-terra>

example_docs/docs/sphinx_guide/custom_directives.rst

@@ -0,0 +1,51 @@
+=================
+Custom Directives
+=================
+
+qiskit-call-to-action-item
+==========================
+
+.. raw:: html
+
+   <div class="tutorials-callout-container">
+      <div class="row">
+
+.. qiskit-call-to-action-item::
+   :header: Go back to qiskit.org!
+   :description: That's a cool site too :)
+   :button_link:  https://qiskit.org
+   :button_text: qiskit.org
+
+.. raw:: html
+
+      </div>
+   </div>
+
+
+qiskit-card-item
+================
+
+.. raw:: html
+
+  <div id="tutorial-cards-container">
+  <hr class="tutorials-hr">
+  <div class="row">
+  <div id="tutorial-cards">
+  <div class="list">
+
+..
+  Note: To get the `image` working locally, we have to use a relative link like `../`. In
+  production, it should simply be `_static/ibm_qlab.png.
+
+.. qiskit-card-item::
+  :header: IBM Quantum Lab
+  :card_description: Build quantum applications and experiments with Qiskit in a cloud programming environment.
+  :image: ../_static/ibm_qlab.png
+  :link: https://quantum-computing.ibm.com/
+
+.. raw:: html
+
+  </div>
+  </div>
+  </div>
+  </div>

qiskit_sphinx_theme/__init__.py

@@ -1,9 +1,21 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020, 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.
+
 """Pytorch Sphinx theme."""
 
 from pathlib import Path
 from warnings import warn
 
-from qiskit_sphinx_theme import translations
+from qiskit_sphinx_theme import directives, translations
 
 __version__ = '1.11.0rc1'
 __version_full__ = __version__
@@ -34,8 +46,8 @@ def get_html_theme_path():
 
 # See https://www.sphinx-doc.org/en/master/development/theming.html
 def setup(app):
-    # We always activate translations support, but users need to set `translations_list` in config
-    # for it to be used.
+    # We always activate these plugins, but users need to use them to actually do anything.
+    directives.setup(app)
     translations.setup(app)
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch_base"))

qiskit_sphinx_theme/directives.py

@@ -0,0 +1,107 @@
+# 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.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import StringList
+
+if TYPE_CHECKING:
+    import sphinx.application
+
+
+def setup(app: sphinx.application.Sphinx) -> None:
+    app.add_directive(CardItemDirective.NAME, CardItemDirective)
+    app.add_directive(CallToActionItemDirective.NAME, CallToActionItemDirective)
+
+
+class CardItemDirective(Directive):
+    NAME = "qiskit-card-item"
+
+    option_spec = {
+        "header": directives.unchanged,
+        "image": directives.unchanged,
+        "link": directives.unchanged,
+        "card_description": directives.unchanged,
+        "tags": directives.unchanged,
+    }
+
+    def run(self):
+        header = self.options.get("header")
+        if header is None:
+            raise ValueError(f"`header` not set in {self.NAME} directive")
+        image_source = self.options.get('image')
+        if image_source is None:
+            raise ValueError(f"`image` not set in {self.NAME} directive")
+        link = self.options.get("link", "")
+        card_description = self.options.get("card_description", "")
+        tags = self.options.get("tags", "")
+
+        card_rst = f"""
+.. raw:: html
+
+    <div class="col-md-12 tutorials-card-container" data-tags={tags}>
+    <div class="card tutorials-card" link={link}>
+    <div class="card-body">
+    <div class="card-title-container">
+        <h4>{header}</h4>
+    </div>
+    <p class="card-summary">{card_description}</p>
+    <p class="tags">{tags}</p>
+    <div class="tutorials-image"><img src='{image_source}'></div>
+    </div>
+    </div>
+    </div>
+"""
+        card_list = StringList(card_rst.splitlines())
+        card = nodes.paragraph()
+        self.state.nested_parse(card_list, self.content_offset, card)
+        return [card]
+
+
+class CallToActionItemDirective(Directive):
+    NAME = "qiskit-call-to-action-item"
+
+    option_spec = {
+        "header": directives.unchanged,
+        "description": directives.unchanged,
+        "button_link": directives.unchanged,
+        "button_text": directives.unchanged,
+    }
+
+    def run(self):
+        description = self.options.get("description", "")
+        header = self.options.get("header")
+        if header is None:
+            raise ValueError(f"`header` not set in {self.NAME} directive")
+        button_link = self.options.get("button_link", "")
+        button_text = self.options.get("button_text", "")
+
+        callout_rst = f"""
+.. 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>
+"""
+
+        callout_list = StringList(callout_rst.splitlines())
+        callout = nodes.paragraph()
+        self.state.nested_parse(callout_list, self.content_offset, callout)
+        return [callout]

qiskit_sphinx_theme/translations.py

@@ -1,6 +1,6 @@
 # This code is part of Qiskit.
 #
-# (C) Copyright IBM 2018, 2023.
+# (C) Copyright IBM 2021, 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

setup.py

@@ -29,6 +29,7 @@
         "Framework :: Sphinx :: Theme",
     ],
     install_requires=[
+        "docutils",
         "furo @ git+https://github.com/pradyunsg/furo.git@48c0bf2aa983fb1ccd79b4167fe85387249afedf",
         "sphinx",
         "sphinxcontrib-jquery",  # Remove once we get rid of the Pytorch theme.