Build conceptual and API docs with Sphinx

.github/workflows/ci.yml

@@ -1,61 +1,100 @@
-name: CI
-on:
-  push:
-    branches:
-    - main
-  pull_request:
-    branches:
-    - main
-    - feature/*
-    - features/*
-
-env:
-  CARGO_TERM_COLOR: always
-
-jobs:
-  build:
-    runs-on: ${{ matrix.config.os }}
-    env: ${{ matrix.config.env }}
-    strategy:
-      fail-fast: false
-      matrix:
-        config:
-          - {
-              os: "ubuntu-20.04",
-              arch: "amd64",
-              env: {},
-            }
-          - {
-              os: "windows-2019",
-              arch: "amd64",
-              env: {},
-            }
-          - {
-              os: "macOS-10.15",
-              arch: "amd64",
-              env: {},
-            }
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          submodules: 'recursive'
-      - name: Linux - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
-        run: sudo apt-get install -y ccache ninja-build
-        if: ${{ matrix.config.os == 'ubuntu-20.04' }}
-      - name: Windows - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
-        run: choco install --accept-license -y sccache ninja
-        if: ${{ matrix.config.os == 'windows-2019' }}
-      - name: MacOS - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
-        run: brew install ccache ninja
-        if: ${{ matrix.config.os == 'macOS-10.15' }}
-      - name: Windows - Install LLVM 11.1.0
-        run: choco install llvm --version=11.1.0 --allow-downgrade
-        if: ${{ matrix.config.os == 'windows-2019' }}
-      - name: "Build all"
-        run: ./build.ps1
-        shell: pwsh
-      - name: Artifacts
-        uses: actions/upload-artifact@v2
-        with:
-          name: artifacts
-          path: target/wheels/*
+name: CI
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+    branches:
+    - main
+    - feature/*
+    - features/*
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ${{ matrix.config.os }}
+    env: ${{ matrix.config.env }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {
+              os: "ubuntu-20.04",
+              arch: "amd64",
+              env: {},
+            }
+          - {
+              os: "windows-2019",
+              arch: "amd64",
+              env: {},
+            }
+          - {
+              os: "macOS-10.15",
+              arch: "amd64",
+              env: {},
+            }
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
+      - name: Linux - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
+        run: sudo apt-get install -y ccache ninja-build
+        if: ${{ matrix.config.os == 'ubuntu-20.04' }}
+      - name: Windows - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
+        run: choco install --accept-license -y sccache ninja
+        if: ${{ matrix.config.os == 'windows-2019' }}
+      - name: MacOS - Install build dependencies, ccache, and update PATH to use linked versions of gcc, cc, etc
+        run: brew install ccache ninja
+        if: ${{ matrix.config.os == 'macOS-10.15' }}
+      - name: Windows - Install LLVM 11.1.0
+        run: choco install llvm --version=11.1.0 --allow-downgrade
+        if: ${{ matrix.config.os == 'windows-2019' }}
+      - name: "Build all"
+        run: ./build.ps1
+        shell: pwsh
+      - name: Artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: artifacts
+          path: target/wheels/*
+
+  docs:
+    runs-on: "ubuntu-20.04"
+    needs: build
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: false
+
+      - name: Download Build Artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: artifacts
+          path: wheelhouse
+
+      - name: Build Docs
+        run: |
+          $properties = @{
+            "wheelhouse" = (Resolve-Path "wheelhouse/*-linux_x86_64.whl")
+          };
+          ./eng/build.ps1 `
+            -taskList docs `
+            -properties $properties
+        shell: pwsh
+
+      # Always publish docs as an artifact, but only publish docs to GitHub Pages
+      # when pushing to main.
+      - name: Publish Docs as Artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: docs/_build
+
+      - name: Publish Docs to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@4.1.7
+        with:
+          branch: gh-pages
+          folder: docs/_build/html
+        if: ${{ github.event_name == 'push' }}

.gitignore

@@ -123,6 +123,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.docs-venv
 
 # Spyder project settings
 .spyderproject

docs/Makefile

@@ -0,0 +1,21 @@
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/apiref/generator.md

@@ -0,0 +1,10 @@
+# pyqir_generator
+
+## `QirBuilder` class
+
+:::{eval-rst}
+.. autoclass:: pyqir_generator.QirBuilder
+    :show-inheritance:
+    :members:
+    :undoc-members:
+:::

docs/apiref/index.md

@@ -0,0 +1,11 @@
+# API Reference
+
+:::{toctree}
+---
+maxdepth: 2
+---
+
+parser
+generator
+jit
+:::

docs/apiref/jit.md

@@ -0,0 +1,28 @@
+# pyqir_jit
+
+## `NonadaptiveJit` class
+
+:::{eval-rst}
+.. autoclass:: pyqir_jit.NonadaptiveJit
+    :show-inheritance:
+    :members:
+    :undoc-members:
+:::
+
+## `GateSet` class
+
+:::{eval-rst}
+.. autoclass:: pyqir_jit.GateSet
+    :show-inheritance:
+    :members:
+    :undoc-members:
+:::
+
+## `GateLogger` class
+
+:::{eval-rst}
+.. autoclass:: pyqir_jit.GateLogger
+    :show-inheritance:
+    :members:
+    :undoc-members:
+:::