wip: Build docs using pdoc

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"]
 

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"))

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"]

quil-py/quil/expression.py

@@ -0,0 +1 @@
+from .quil.expression import *

quil-py/quil/instructions.py

@@ -0,0 +1 @@
+from .quil.instructions import *

quil-py/quil/program.py

@@ -0,0 +1 @@
+from .quil.program import *