From 40f1aa568e60813c9ed53113739d3a2ff3753693 Mon Sep 17 00:00:00 2001
From: Marquess Valdez <marquessavaldez@gmail.com>
Date: Fri, 3 Nov 2023 15:19:48 -0700
Subject: [PATCH] wip: Build docs using pdoc

---
 Cargo.lock                   |  6 ++----
 quil-py/Makefile.toml        |  8 ++++++++
 quil-py/make_docs.py         | 19 +++++++++++++++++++
 quil-py/pyproject.toml       |  1 +
 quil-py/quil/expression.py   |  1 +
 quil-py/quil/instructions.py |  1 +
 quil-py/quil/program.py      |  1 +
 7 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 quil-py/make_docs.py
 create mode 100644 quil-py/quil/expression.py
 create mode 100644 quil-py/quil/instructions.py
 create mode 100644 quil-py/quil/program.py

diff --git a/Cargo.lock b/Cargo.lock
index 561972b8..dfd836e2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1046,7 +1046,7 @@ checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
 [[package]]
 name = "quil-py"
-version = "0.5.6"
+version = "0.6.0"
 dependencies = [
  "ndarray",
  "numpy",
@@ -1059,7 +1059,7 @@ dependencies = [
 
 [[package]]
 name = "quil-rs"
-version = "0.21.5"
+version = "0.22.0"
 dependencies = [
  "approx",
  "clap",
@@ -1223,8 +1223,6 @@ checksum = "4bf2521270932c3c7bed1a59151222bd7643c79310f2916f01925e1e16255698"
 [[package]]
 name = "rigetti-pyo3"
 version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19ada0e718c50ee8e934a1791207fcb6543e237cd439d76d47eaf4dbcfa329fd"
 dependencies = [
  "num-complex",
  "num-traits",
diff --git a/quil-py/Makefile.toml b/quil-py/Makefile.toml
index 909d0e94..2a6086b1 100644
--- a/quil-py/Makefile.toml
+++ b/quil-py/Makefile.toml
@@ -31,6 +31,14 @@ dependencies = [
     "pytest",
 ]
 
+[tasks.py-docs]
+dependencies = [
+    "poetry-install",
+    "install-quil"
+]
+command = "poetry"
+args = ["run", "python", "make_docs.py"]
+
 [tasks.dev-flow]
 dependencies = ["dev-test-flow", "pytest-flow", "stubtest"]
 
diff --git a/quil-py/make_docs.py b/quil-py/make_docs.py
new file mode 100644
index 00000000..8eadd8c4
--- /dev/null
+++ b/quil-py/make_docs.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+import sys
+
+import pdoc
+
+import quil  # noqa - we need to import quil for it to appear in sys.modules
+
+
+if __name__ == "__main__":
+    # Workaround for an incompatiblity between pdoc and how we expose the quil
+    # package from pyo3. This module hierarchy isn't valid in a real Python
+    # environment, but overriding module.__name__ here helps pdoc import the
+    # right module internally.
+    # Possibly related issue: https://github.com/mitmproxy/pdoc/issues/633
+    for qualified_name, module in sys.modules.items():
+        if qualified_name.startswith("quil.") and qualified_name.count(".") == 1:
+            module.__name__ = qualified_name
+
+    pdoc.pdoc("quil", "!quil.quil", output_directory=Path("docs"))
diff --git a/quil-py/pyproject.toml b/quil-py/pyproject.toml
index 1df73880..cafbf996 100644
--- a/quil-py/pyproject.toml
+++ b/quil-py/pyproject.toml
@@ -32,6 +32,7 @@ black = "^23.1.0"
 maturin = "^1.2.3"
 mypy = "^1.1.1"
 pytest = "^7.2.2"
+pdoc = "^14.1.0"
 
 [tool.maturin]
 features = ["pyo3/extension-module"]
diff --git a/quil-py/quil/expression.py b/quil-py/quil/expression.py
new file mode 100644
index 00000000..d722e58f
--- /dev/null
+++ b/quil-py/quil/expression.py
@@ -0,0 +1 @@
+from .quil.expression import *
diff --git a/quil-py/quil/instructions.py b/quil-py/quil/instructions.py
new file mode 100644
index 00000000..4b3a779a
--- /dev/null
+++ b/quil-py/quil/instructions.py
@@ -0,0 +1 @@
+from .quil.instructions import *
diff --git a/quil-py/quil/program.py b/quil-py/quil/program.py
new file mode 100644
index 00000000..26c468fd
--- /dev/null
+++ b/quil-py/quil/program.py
@@ -0,0 +1 @@
+from .quil.program import *