doc(quil-py): Publish documentation to https://rigetti.github.io/quil-rs

(#314)
rigetti · Dec 12, 2023 · 655ff3f · 655ff3f
1 parent 63afe38
commit 655ff3f
Showing 23 changed files with 1,194 additions and 132 deletions.
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -0,0 +1,47 @@
+name: Publish quil-py documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install poetry
+        uses: snok/install-poetry@v1
+      - uses: Swatinem/rust-cache@v2
+      - name: Install cargo-make
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: --debug cargo-make
+      - name: Build quil-py documentation
+        uses: actions-rs/cargo@v1
+        with:
+          command: make
+          args: --cwd quil-py --makefile Makefile.toml docs
+      - name: Deploy preview
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: quil-py/build/docs
+          preview-branch: quil-py-docs
+      - name: Deploy docs
+        if: ${{ github.event_name == 'push' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: quil-py/build/docs
+          publish_branch: quil-py-docs
diff --git a/.github/workflows/publish-quil-py.yml b/.github/workflows/publish-quil-py.yml
@@ -176,7 +176,7 @@ jobs:
   publish-rust-crate:
     name: Release
     runs-on: ubuntu-latest
-    needs: [ publish-python-package ]
+    needs: publish-python-package
     steps:
       - uses: actions/checkout@v3
         with:

diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,8 @@ node_modules
 # Python artifacts
 *.so
 __pycache__
+**./.null-ls-cache*
+
+# quil-py documentation
+quil-py/build
+
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/quil-py/Cargo.toml b/quil-py/Cargo.toml
@@ -27,7 +27,7 @@ strum.workspace = true
 # pyo3 dependencies should be updated together
 numpy = "0.20.0"
 pyo3 = "0.20.0"
-rigetti-pyo3 = "0.3"
+rigetti-pyo3 = "0.3.1"
 
 [build-dependencies]
 pyo3-build-config = "0.20.0"
diff --git a/quil-py/Makefile.toml b/quil-py/Makefile.toml
@@ -31,6 +31,11 @@ dependencies = [
     "pytest",
 ]
 
+[tasks.docs]
+dependencies = ["poetry-install", "install-quil"]
+command = "poetry"
+args = ["run", "pdoc", "-o", "build/docs", "quil", "!quil.quil", "--logo", "https://qcs.rigetti.com/static/img/rigetti-logo.svg"]
+
 [tasks.dev-flow]
 dependencies = ["dev-test-flow", "pytest-flow", "stubtest"]
 

diff --git a/quil-py/README-py.md b/quil-py/README-py.md
@@ -5,3 +5,7 @@
 The `quil` package provides tools for constructing, manipulating, parsing, and printing [Quil](https://github.com/quil-lang/quil) programs. Internally, it is powered by [quil-rs](https://github.com/rigetti/quil-rs).
 
 This package is still in early development and breaking changes should be expected between minor versions.
+
+# Documentation
+
+Documentation for the current release of `quil` is published [here](https://rigetti.github.io/quil-rs/quil.html). Every version of `quil` ships [with type stubs](https://github.com/rigetti/quil-rs/tree/main/quil-py/quil) that provide type hints and documentation to Python tooling and editors that support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) or similar.
diff --git a/quil-py/make_docs.py b/quil-py/make_docs.py
@@ -0,0 +1,15 @@
+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__":
+    print(dir(sys.modules["quil"]))
+    print(dir(sys.modules["quil.validation"]))
+    print([k for k in sys.modules.keys() if "quil" in k])
+    del sys.modules["quil.validation"]
+
+    pdoc.pdoc("quil", "!quil.quil", output_directory=Path("docs"))
diff --git a/quil-py/out/index.html b/quil-py/out/index.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./quil.html"/>
+</head>
+</html>
diff --git a/quil-py/out/quil.html b/quil-py/out/quil.html
diff --git a/quil-py/out/quil/quil.html b/quil-py/out/quil/quil.html
diff --git a/quil-py/out/search.js b/quil-py/out/search.js
diff --git a/quil-py/poetry.lock b/quil-py/poetry.lock
diff --git 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.html b/quil-py/quil.html
diff --git a/quil-py/quil/__init__.py b/quil-py/quil/__init__.py
@@ -1 +1,6 @@
+"""
+The `quil` package provides tools for constructing, manipulating, parsing, and printing [Quil](https://github.com/quil-lang/quil) programs.
+
+⚠️ This package is still in early development and breaking changes should be expected between minor versions.
+"""
 from .quil import *
diff --git a/quil-py/quil/expression/__init__.py b/quil-py/quil/expression/__init__.py
@@ -0,0 +1 @@
+from quil.expression import *
diff --git a/quil-py/quil/expression/__init__.pyi b/quil-py/quil/expression/__init__.pyi
@@ -1,3 +1,6 @@
+"""
+The ``expression`` module contains classes for representing Quil expressions.
+"""
 from enum import Enum
 from typing import Dict, final, Sequence, Optional, Union
 
@@ -14,30 +17,30 @@ class Expression:
     """
     A Quil expression.
 
-    Variants:
-        ``address``: An address defined by a ``MemoryReference``.
-        ``function_call``: A ``FunctionCall``.
-        ``infix``: An ``InfixExpression``.
-        ``number``: A number defined as a ``complex``.
-        ``pi``: The constant `pi`. No inner data.
-        ``prefix``: A ``PrefixExpression``.
-        ``variable``: A variable defined as a ``str``.
+    # Variants:
+    - ``address``: An address defined by a `quil.instructions.MemoryReference`.
+    - ``function_call``: A `FunctionCallExpression`.
+    - ``infix``: An `InfixExpression`.
+    - ``number``: A number defined as a `complex`.
+    - ``pi``: The constant ``pi``. No inner data.
+    - ``prefix``: A `PrefixExpression`.
+    - ``variable``: A variable defined as a `str`.
 
     As seen above, some variants contain inner data that fully specify the expression.
     For example, the ``number`` variant contains an ``int``. This is in contrast to variants like
     ``pi`` that have no inner data because they require none to fully specify the expression.
     This difference is important for determining which methods are available for each variant.
 
-    Methods (for each variant):
-        ``is_*``: Returns ``True`` if the expression is that variant, ``False`` otherwise.
+    Methods (for every variant):
+    - ``is_*``: Returns ``True`` if the expression is that variant, ``False`` otherwise.
 
-        If the variant has inner data:
-            ``as_*``: returns the inner data if it is the given variant, ``None`` otherwise.
-            ``to_*``: returns the inner data if it is the given variant, raises ``ValueError`` otherwise.
-            ``from_*``: Creates a new ``Expression`` of the given variant from an instance of the inner type.
+    If the variant has inner data:
+    - ``as_*``: returns the inner data if it is the given variant, ``None`` otherwise.
+    - ``to_*``: returns the inner data if it is the given variant, raises ``ValueError`` otherwise.
+    - ``from_*``: Creates a new ``Expression`` of the given variant from an instance of the inner type.
 
-        If the variant doesn't have inner data (e.g. ``pi``)
-            ``new_*``: Creates a new ``Expression`` for the variant
+    If the variant doesn't have inner data (e.g. ``pi``)
+    - ``new_*``: Creates a new ``Expression`` for the variant
     """
 
     def inner(
@@ -113,7 +116,7 @@ class Expression:
         ...
     def to_real(self) -> float:
         """
-        If this is a number with imaginary part "equal to" zero (of _small_ absolute value), return
+        If this is a number with imaginary part "equal to" zero (of <em>small</em> absolute value), return
         that number. Otherwise, raises an ``EvaluationError``
         """
     def __add__(self, other: "Expression") -> "Expression": ...
@@ -134,6 +137,9 @@ class Expression:
         """
 
 class FunctionCallExpression:
+    """
+    A Quil function call.
+    """
     @staticmethod
     def __new__(cls, function: ExpressionFunction, expression: Expression) -> "FunctionCallExpression": ...
     @property
@@ -146,6 +152,9 @@ class FunctionCallExpression:
     def expression(self, expression: Expression): ...
 
 class InfixExpression:
+    """
+    A Quil infix expression.
+    """
     @staticmethod
     def __new__(cls, left: Expression, operator: InfixOperator, right: Expression): ...
     @property
@@ -162,6 +171,9 @@ class InfixExpression:
     def right(self, expression: Expression): ...
 
 class PrefixExpression:
+    """
+    A Quil prefix expression.
+    """
     @staticmethod
     def __new__(cls, operator: PrefixOperator, expression: Expression): ...
     @property
@@ -175,6 +187,9 @@ class PrefixExpression:
 
 @final
 class ExpressionFunction(Enum):
+    """
+    An enum representing a Quil function that can be applied to an expression.
+    """
     Cis = "CIS"
     Cosine = "COSINE"
     Exponent = "EXPONENT"
@@ -183,11 +198,17 @@ class ExpressionFunction(Enum):
 
 @final
 class PrefixOperator(Enum):
+    """
+    An enum that represents the operators supported on a prefix expression.
+    """
     Plus = "PLUS"
     Minus = "MINUS"
 
 @final
 class InfixOperator(Enum):
+    """
+    An enum that represents the operators supported on an infix expression.
+    """
     Caret = "CARET"
     Plus = "PLUS"
     Minus = "MINUS"

diff --git a/quil-py/quil/instructions/__init__.py b/quil-py/quil/instructions/__init__.py
@@ -0,0 +1,4 @@
+"""
+The `quil.instructions` module contains classes for representing Quil instructions.
+"""
+from quil.instructions import *