Add demo showcase. (#70)

* Add demo showcase.

* Remove jigsaw graphic.

* Tweak language.

Co-authored-by: Olivia Di Matteo <dimatteo.olivia@gmail.com>

README.rst

@@ -27,7 +27,7 @@ PennyLane Forest Plugin
 
 .. header-start-inclusion-marker-do-not-remove
 
-Contains the PennyLane Forest plugin. This plugin allows different Rigetti devices to work with
+The PennyLane Forest plugin allows different Rigetti devices to work with
 PennyLane --- the wavefunction simulator, and the Quantum Virtual Machine (QVM).
 
 `pyQuil <https://pyquil.readthedocs.io>`__ is a Python library for quantum programming using the

doc/conf.py

@@ -341,8 +341,8 @@
 #autodoc_default_flags = ['members']
 autosummary_generate = True
 
-from directives import CustomDeviceGalleryItemDirective
+from directives import CustomDeviceGalleryItemDirective, CustomDemoGalleryItemDirective
 
 def setup(app):
     app.add_directive('devicegalleryitem', CustomDeviceGalleryItemDirective)
-
+    app.add_directive('demogalleryitem', CustomDemoGalleryItemDirective)

doc/directives.py

@@ -86,3 +86,79 @@ def run(self):
         thumb = nodes.paragraph()
         self.state.nested_parse(thumbnail, self.content_offset, thumb)
         return [thumb]
+
+DEMO_GALLERY_TEMPLATE = """
+.. raw:: html
+
+   <a href={link} data-toggle="tooltip" title="{tooltip}">
+    <div class="card" style="width: 15rem; height: 19rem; margin: 10px;">
+         <div class="card-header d-flex align-items-center justify-content-center" style="height: 4rem;">
+              <div align="center"> <b> {name} </b> </div>
+         </div>
+         <div class="card-body" align="center">
+           <img src="{figure}" style="max-width: 95%; max-height: 200px;" alt={name}>
+         </div>
+     </div>
+   </a>
+"""
+
+
+class CustomDemoGalleryItemDirective(Directive):
+    """Create a sphinx gallery style thumbnail for demos.
+    Example usage:
+    .. customgalleryitem::
+        :name: Demo title
+        :tooltip: Tooltip text
+        :figure: /_static/path/to/image
+        :link: https://pennylaneqiskit.readthedocs.io/en/latest/
+    """
+
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {'name' : directives.unchanged,
+                   'tooltip': directives.unchanged,
+                   'figure': directives.unchanged,
+                   'link': directives.unchanged}
+
+    has_content = False
+    add_index = False
+
+    def run(self):
+        try:
+            if 'name' in self.options:
+                name = self.options['name']
+            else:
+                raise ValueError('name not found')
+
+            if 'tooltip' in self.options:
+                tooltip = self.options['tooltip'][:195]
+            else:
+                raise ValueError('tooltip not found')
+
+            if 'figure' in self.options:
+                figure = self.options['figure']
+            else:
+                raise ValueError('figure not found')
+
+            if 'link' in self.options:
+                link = self.options['link']
+            else:
+                raise ValueError('link not found')
+
+        except FileNotFoundError as e:
+            print(e)
+            return []
+        except ValueError as e:
+            print(e)
+            raise
+            return []
+
+        thumbnail_rst = DEMO_GALLERY_TEMPLATE.format(name=name,
+                                                     tooltip=tooltip,
+                                                     figure=figure,
+                                                     link=link)
+        thumbnail = StringList(thumbnail_rst.split('\n'))
+        thumb = nodes.paragraph()
+        self.state.nested_parse(thumbnail, self.content_offset, thumb)
+        return [thumb]

doc/index.rst

@@ -3,13 +3,6 @@ PennyLane-Forest Plugin
 
 :Release: |release|
 
-.. image:: _static/puzzle_forest.png
-    :align: center
-    :width: 70%
-    :target: javascript:void(0);
-
-|
-
 .. include:: ../README.rst
   :start-after:	header-start-inclusion-marker-do-not-remove
   :end-before: header-end-inclusion-marker-do-not-remove
@@ -45,18 +38,42 @@ Currently, PennyLane-Forest provides these Forest devices for PennyLane:
 Tutorials
 ~~~~~~~~~
 
-To see the PennyLane-Forest plugin in action, you can use any of the qubit based `demos
-from the PennyLane documentation <https://pennylane.ai/qml/demonstrations.html>`_, for example
-the tutorial on `qubit rotation <https://pennylane.ai/qml/demos/tutorial_qubit_rotation.html>`_,
-and simply replace ``'default.qubit'`` with a ``'forest.XXX'`` device:
+Check out these demos to see the PennyLane-Forest plugin in action:
+
+.. raw:: html
+
+    <div class="row">
+
+.. demogalleryitem::
+    :name: Ensemble classification with Forest and Qiskit devices
+    :figure: https://pennylane.ai/qml/_images/ensemble_diagram.png
+    :link:  https://pennylane.ai/qml/demos/tutorial_ensemble_multi_qpu.html
+    :tooltip: Use multiple QPUs to improve classification.
+
+.. demogalleryitem::
+    :name: PyTorch and noisy devices
+    :figure: https://pennylane.ai/qml/_images/bloch.gif
+    :link:  https://pennylane.ai/qml/demos/pytorch_noise.html
+    :tooltip: Extend PyTorch with real quantum computing power.
+
+.. raw:: html
+
+    </div></div><div style='clear:both'> <br/>
+
+
+You can also try it out using any of the qubit based `demos from the PennyLane documentation
+<https://pennylane.ai/qml/demonstrations.html>`_, for example the tutorial on
+`qubit rotation <https://pennylane.ai/qml/demos/tutorial_qubit_rotation.html>`_.
+Simply replace ``'default.qubit'`` with a ``'forest.XXX'`` device if you have an API key for
+hardware access.
 
 .. code-block:: python
 
     dev = qml.device('forest.XXX', wires=XXX)
 
-Tutorials that originally showcase the forest device are the demos on
-`noisy devices <https://pennylane.ai/qml/demos/pytorch_noise.html>`_ and
-`ensemble classification <https://pennylane.ai/qml/demos/tutorial_ensemble_multi_qpu.html>`_.
+.. raw:: html
+
+    <br/>
 
 .. toctree::
    :maxdepth: 2