Add qiskit-card-item and qiskit-call-to-action-item directives (#326

) Closes #323. These are used by several Qiskit projects, so we should de-duplicate them. ![Screenshot 2023-05-16 at 10 02 55 AM](https://github.com/Qiskit/qiskit_sphinx_theme/assets/14852634/9c672417-6451-4547-bc36-10709f7f3880) ## Alternative considered: stop using these elements For example, these elements will be somewhat tricky to get working with Furo: #327. We considered removing these design elements and instead using standard Sphinx. For example, rather than having `qiskit-call-to-action-item` with its clickable button to go to a URL, we could instead rely on normal Sphinx links, or the left table of contents, and decide we don't care about the button. We decided that we like these design elements enough to keep them. It would be a UX regression to remove them. We may want to improve the styling—but we will still need the RST directive. We may also remove these directives in some future, but only after finding a better alternative. --------- Co-authored-by: Abby Mitchell <[email protected]>
Qiskit · May 16, 2023 · e89b094 · e89b094
1 parent e8c3ae0
commit e89b094
Show file tree

Hide file tree

Showing 7 changed files with 185 additions and 4 deletions.
diff --git a/README.md b/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`. 

diff --git a/example_docs/docs/index.rst b/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>
diff --git a/example_docs/docs/sphinx_guide/custom_directives.rst b/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>
diff --git a/qiskit_sphinx_theme/__init__.py b/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 in their `.rst` files to actually do anything.
+    directives.setup(app)
     translations.setup(app)
 
     app.add_html_theme("qiskit_sphinx_theme", _get_theme_absolute_path("pytorch_base"))

diff --git a/qiskit_sphinx_theme/directives.py b/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]
diff --git a/qiskit_sphinx_theme/translations.py b/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

diff --git a/setup.py b/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.