add sphinx docs

.github/workflows/docs-dev.yml

@@ -0,0 +1,32 @@
+name: Build and deploy documentation for development branch
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  build_and_deploy_docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+          sudo apt update
+          sudo apt install -y pandoc
+      - name: Build docs
+        run: |
+          tox run -e docs
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html/
+          target-folder: dev/

.github/workflows/docs-release.yml

@@ -0,0 +1,34 @@
+name: Build and deploy documentation for release version
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  build_and_deploy_docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+          sudo apt update
+          sudo apt install -y pandoc
+      - name: Build docs
+        run: |
+          tox run -e docs
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html/
+          clean-exclude: |
+            stable/*
+            dev/*

.github/workflows/docs-stable.yml

@@ -0,0 +1,35 @@
+name: Build and deploy documentation for stable version
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  build_and_deploy_docs:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+          sudo apt update
+          sudo apt install -y pandoc
+      - name: Build docs
+        run: |
+          tox run -e docs
+      - name: Set current version
+        run: |
+          echo "version=$(git describe --tags)" >> "$GITHUB_ENV"
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html/
+          target-folder: stable/${{ env.version }}

README.md

@@ -1,21 +1,31 @@
 # qiskit-quimb
 
+<!-- start introduction -->
+
 Simulate [Qiskit](https://www.ibm.com/quantum/qiskit) circuits using [quimb](https://quimb.readthedocs.io/en/latest/).
 
+<!-- end introduction -->
+
 ## Installation
 
+<!-- start installation -->
+
 ```bash
 pip install qiskit-quimb
 ```
 
+<!-- end installation -->
+
 ## Usage
 
 The `qiskit_quimb` module exposes two functions:
 
 - `quimb_circuit`: Converts a Qiskit circuit to a quimb circuit. This is probably the function you want to use.
 - `quimb_gates`: Converts a Qiskit circuit to a list of quimb gates, which is a bit more flexible.
 
-## Example code
+## Code example
+
+<!-- start code-example -->
 
 ```python
 import quimb.tensor
@@ -48,3 +58,5 @@ print(samples)
 ['00', '00', '11', '00', '11', '00', '11', '00', '11', '11']
 ['11', '11', '00', '00', '11', '00', '11', '11', '11', '00']
 ```
+
+<!-- end code-example -->

docs/api/index.md

@@ -0,0 +1,7 @@
+# API reference
+
+```{toctree}
+:maxdepth: 2
+
+qiskit_quimb
+```

docs/api/qiskit_quimb.rst

@@ -0,0 +1,6 @@
+ffsim
+=====
+
+.. automodule:: qiskit_quimb
+   :members:
+   :show-inheritance:

docs/conf.py

@@ -0,0 +1,47 @@
+# (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.
+
+"""Sphinx configuration."""
+
+import importlib.metadata
+
+project = "qiskit-quimb"
+copyright = "2024, IBM"
+author = "Kevin J. Sung"
+release = importlib.metadata.version("qiskit-quimb")
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.extlinks",
+    "sphinx_autodoc_typehints",
+    "myst_parser",
+    "nbsphinx",
+    "qiskit_sphinx_theme",
+]
+
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+
+# HTML output options
+html_theme = "qiskit-ecosystem"
+html_title = f"{project} {release}"
+html_theme_options = {
+    "source_repository": "https://github.com/qiskit-community/qiskit-quimb/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+    "sidebar_qiskit_ecosystem_member": True,
+}
+
+# nbsphinx options (for tutorials)
+nbsphinx_timeout = 300
+nbsphinx_execute = "always"

docs/index.md

@@ -0,0 +1,32 @@
+# ffsim
+
+```{include} ../README.md
+:start-after: <!-- start introduction -->
+:end-before: <!-- end introduction -->
+```
+
+## Installation
+
+```{include} ../README.md
+:start-after: <!-- start installation -->
+:end-before: <!-- end installation -->
+```
+
+## Code example
+
+```{include} ../README.md
+:start-after: <!-- start code-example -->
+:end-before: <!-- end code-example -->
+```
+
+## Contents
+
+```{toctree}
+:maxdepth: 2
+
+tutorials/index
+api/index
+GitHub <https://github.com/qiskit-community/qiskit-quimb>
+Release notes <https://github.com/qiskit-community/qiskit-quimb/releases>
+Development branch docs <https://qiskit-community.github.io/qiskit-quimb/dev/>
+```

docs/tutorials/index.md

@@ -0,0 +1,7 @@
+# Tutorials
+
+```{toctree}
+:maxdepth: 1
+
+quimb-circuit
+```

docs/tutorials/quimb-circuit.ipynb

@@ -0,0 +1,74 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Simulating Qiskit circuits with quimb"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['00', '00', '11', '00', '11', '00', '11', '00', '11', '11']\n",
+      "['11', '11', '00', '00', '11', '00', '11', '11', '11', '00']\n"
+     ]
+    }
+   ],
+   "source": [
+    "import quimb.tensor\n",
+    "from qiskit.circuit import QuantumCircuit, QuantumRegister\n",
+    "\n",
+    "from qiskit_quimb import quimb_circuit\n",
+    "\n",
+    "# Build a Qiskit circuit\n",
+    "qubits = QuantumRegister(2)\n",
+    "circuit = QuantumCircuit(qubits)\n",
+    "a, b = qubits\n",
+    "circuit.h(a)\n",
+    "circuit.cx(a, b)\n",
+    "\n",
+    "# Convert it to a quimb circuit\n",
+    "quimb_circ = quimb_circuit(circuit)\n",
+    "\n",
+    "# Sample 10 bitstrings\n",
+    "samples = list(quimb_circ.sample(10, seed=1234))\n",
+    "print(samples)\n",
+    "\n",
+    "# You can specify the quimb Circuit subclass and keyword arguments for the constructor\n",
+    "quimb_circ = quimb_circuit(\n",
+    "    circuit, quimb_circuit_class=quimb.tensor.CircuitMPS, max_bond=20\n",
+    ")\n",
+    "samples = list(quimb_circ.sample(10, seed=1234))\n",
+    "print(samples)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "qiskit-quimb",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

pyproject.toml

@@ -23,7 +23,19 @@ classifiers = [
 dependencies = ["qiskit", "quimb"]
 
 [project.optional-dependencies]
-dev = ["coverage", "mypy", "pytest", "qiskit[visualization]", "ruff"]
+dev = [
+    "coverage",
+    "mypy",
+    "myst-parser",
+    "nbmake",
+    "nbsphinx",
+    "pytest",
+    "qiskit[visualization]",
+    "qiskit-sphinx-theme",
+    "ruff",
+    "sphinx",
+    "sphinx-autodoc-typehints",
+]
 
 [project.urls]
 Homepage = "https://github.com/qiskit-community/qiskit-quimb"

tox.ini

@@ -44,3 +44,14 @@ extras =
   dev
 commands =
   ruff format --check
+
+[testenv:docs]
+description = build docs
+extras =
+  dev
+setenv =
+  SPHINX_APIDOC_OPTIONS = members,show-inheritance
+commands =
+  python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "stubs", ignore_errors=True)'
+  python -c 'import shutil, pathlib; shutil.rmtree(pathlib.Path("docs") / "_build" / "html" / ".doctrees", ignore_errors=True)'
+  sphinx-build -b html -W {posargs} docs/ docs/_build/html