Docs: Add example notebooks (#13)

Author: ameyer-rigetti

.github/workflows/test.yml

@@ -23,7 +23,6 @@ jobs:
           key: poetry-${{ hashFiles('poetry.lock') }}
       - name: Check style
         run: |
-          sudo apt update
           . scripts/ci_install_deps
           poetry run make check-style
 
@@ -42,7 +41,6 @@ jobs:
           key: poetry-${{ hashFiles('poetry.lock') }}
       - name: Check types
         run: |
-          sudo apt update
           . scripts/ci_install_deps
           poetry run make check-types
 
@@ -64,7 +62,6 @@ jobs:
           key: poetry-${{ hashFiles('poetry.lock') }}
       - name: Test (Python ${{ matrix.python-version }})
         run: |
-          sudo apt update
           . scripts/ci_install_deps
           docker run --rm -itd -p 5555:5555 --entrypoint bash rigetti/quilc -c "curl -L -o qelib1.inc https://raw.githubusercontent.com/Qiskit/qiskit-terra/0.16.2/qiskit/qasm/libs/qelib1.inc && ./quilc -S -P"
           docker run --rm -itd -p 5000:5000 rigetti/qvm -S
@@ -88,6 +85,7 @@ jobs:
           SPHINXOPTS: "-W"
         run: |
           sudo apt update
+          sudo apt install pandoc
           . scripts/ci_install_deps "-E docs"
           poetry run make docs
 
@@ -107,6 +105,5 @@ jobs:
       - name: Check Licenses
         # This is an exact match list, new dependencies will likely require their own entries
         run: |
-          sudo apt update
           . scripts/ci_install_deps
           poetry run pip-licenses --allow-only="MIT License;Apache Software License;BSD License;GNU Lesser General Public License v2 or later (LGPLv2+);Python Software Foundation License;Apache License 2.0;new BSD;Apache-2.0;ISCL;ISC License (ISCL);BSD;Mozilla Public License 2.0 (MPL 2.0)"

.gitignore

@@ -35,6 +35,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+README.rst
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

README.md

@@ -170,4 +170,4 @@ Dependencies are managed with [Poetry](https://python-poetry.org/) so you need t
 1. Check style only: `make check-style`
 1. Check types only: `make check-types`
 1. Reformat all code (to make `check-style` pass): `make format`
-1. Build documentation, serve locally, and watch for changes: `make watch-docs`
+1. Build documentation, serve locally, and watch for changes: `make watch-docs` (requires `docs` extra: `poetry install -E docs`)

docs/conf.py

@@ -17,6 +17,8 @@
     "autoapi.extension",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "nbsphinx",
+    "sphinx.ext.mathjax",
 ]
 
 source_suffix = {
@@ -42,8 +44,9 @@
 # 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 = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
 
+myst_update_mathjax = False
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = "furo"

docs/examples/qaoa_pyquil.ipynb

@@ -9,6 +9,14 @@ This documentation supports light ☀️ and dark 🌙 modes and will automatica
     :end-before: Development
 ```
 
+```{toctree}
+   :maxdepth: 1
+   :caption: Examples
+   
+examples/qaoa_qiskit.ipynb
+examples/qaoa_pyquil.ipynb
+```
+
 ```{toctree}
    :maxdepth: 2
    :caption: API Reference