doc(python): Publish documentation on GitHub pages (#412)

---------

Co-authored-by: Kalan <[email protected]>

.github/workflows/publish-docs.yml

@@ -0,0 +1,48 @@
+name: Publish qcs-sdk-python 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 qcs-sdk-python documentation
+        uses: actions-rs/cargo@v1
+        with:
+          command: make
+          args: --cwd crates/python --makefile Makefile.toml docs
+      - name: Deploy preview
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: crates/python/build/docs
+          preview-branch: qcs-sdk-python-docs
+      - name: Deploy docs
+        if: ${{ github.event_name == 'push' }}
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: crates/python/build/docs
+          publish_branch: qcs-sdk-python-docs
+

.gitignore

@@ -25,5 +25,7 @@ qcs-api/docs
 
 # Python artifacts
 **/__pycache__
+**/null-ls-cache*
 crates/python/.hypothesis
 crates/python/qcs_sdk/*.so
+crates/python/build

Cargo.toml

@@ -27,7 +27,7 @@ numpy = "0.20.0"
 pyo3 = "0.20.0"
 pyo3-asyncio = { version = "0.20", features = ["tokio-runtime"] }
 pyo3-build-config = "0.20.0"
-rigetti-pyo3 = { version = "0.3.0", features = ["complex"] }
+rigetti-pyo3 = { version = "0.3.1", features = ["complex"] }
 
 # The primary intent of these options is to reduce the binary size for Python wheels
 # since PyPi has limits on how much storage a project can use.

crates/python/Makefile.toml

@@ -57,3 +57,9 @@ alias = "dev-flow"
 
 [tasks.ci-flow]
 dependencies = ["pytest-flow", "stubtest"]
+
+[tasks.docs]
+dependencies = ["poetry-install", "install-lib"]
+command = "poetry"
+args = ["run", "pdoc", "-o", "build/docs", "qcs_sdk", "!qcs_sdk.qcs_sdk", "--logo", "https://qcs.rigetti.com/static/img/rigetti-logo.svg"]
+

crates/python/README.md

@@ -8,6 +8,10 @@ to compile and run Quil programs on Rigetti quantum processors. Internally, it i
 While this package can be used directly, [pyQuil](https://pypi.org/project/pyquil/) offers more functionality and a 
 higher-level interface for building and executing Quil programs. This package is still in early development and breaking changes should be expected between minor versions.
 
+# Documentation
+
+Documentation for the current release of `qcs_sdk` is published [here](https://rigetti.github.io/qcs-sdk-rust/qcs_sdk.html). Every version of `qcs_sdk` ships [with type stubs](https://github.com/rigetti/qcs-sdk-rust/tree/main/crates/python/qcs_sdk) that can provide type hints and documentation to Python tooling and editors.
+
 ## Troubleshooting
 
 ### Enabling Debug logging

crates/python/pyproject.toml

@@ -53,6 +53,7 @@ pytest-asyncio = "^0.19.0"
 black = "^22.8.0"
 syrupy = "^3.0.6"
 mypy = "^1.4.1"
+pdoc = "^14.1.0"
 
 [build-system]
 requires = ["maturin>=1.0.0,<2.0.0"]