feat: pypi package with autodoc

.github/workflows/pre-commit-au.yml

@@ -0,0 +1,21 @@
+name: Pre-commit auto-update
+
+on:
+  # every day at midnight
+  schedule:
+    - cron: "0 0 * * *"
+  # on demand
+  workflow_dispatch:
+
+jobs:
+  upgrade:
+    uses: browniebroke/github-actions/.github/workflows/pre-commit-autoupdate.yml@v1
+    secrets:
+      gh_pat: ${{ secrets.GITHUB_TOKEN }}
+    with:
+      # Inputs listed with their default (all optional)
+      config_path: ".pre-commit-config.yaml" # path is relative to repository root
+      python_version: "3.11"
+      branch_name: "update/pre-commit-hooks"
+      pull_request_title: "chore(deps): upgrade pre-commit dependencies"
+      commit_message: "chore(deps): upgrade pre-commit dependencies"

.github/workflows/python-app.yml

@@ -32,3 +32,14 @@ jobs:
     - name: Run tests
       run: |
         python -m pytest
+    - name: Sphinx documentation build
+      run: |
+        make docs
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && matrix.python-version == '3.11' }}
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html/
+        force_orphan: true

.github/workflows/python-publish.yml

@@ -0,0 +1,35 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see:
+# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1

.pre-commit-config.yaml

@@ -13,34 +13,34 @@ repos:
       - id: debug-statements
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.16.21
+    rev: v1.16.23
     hooks:
       - id: typos
 
   - repo: https://github.com/keewis/blackdoc
-    rev: v0.3.8
+    rev: v0.3.9
     hooks:
     -   id: blackdoc
         additional_dependencies:
         - black==23.10.1
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.4
+    rev: v0.1.5
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.6.1'
+    rev: 'v1.7.0'
     hooks:
     - id: mypy
       pass_filenames: false
       args: [--package=pytket.phir, --package=tests]
       additional_dependencies: [
+        phir,
         pytest,
-        pytket==1.21.0,
         pytket-quantinuum==0.25.0,
+        pytket==1.21.0,
         types-setuptools,
-        "phir",
       ]

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2023-11-17
+
+First release.
+
+[0.1.0]: https://github.com/CQCL/pytket-phir/commits/v0.1.0
+[unreleased]: https://github.com/CQCL/pytket-phir/compare/v0.1.0...HEAD
+
+<!-- markdownlint-configure-file {"MD024": {"siblings_only" : true}, "MD034": false} -->

MANIFEST.in

@@ -1,10 +1,11 @@
-include *.toml
+include *.md
 include *.txt
 include Makefile
 include mypy.ini
 recursive-include docs *.rst
 recursive-include docs Makefile
 recursive-include tests *.qasm
-exclude Dockerfile
-exclude .docker*
-exclude .pre-commit*
+
+exclude .pre-commit-config.yaml
+exclude mypy.ini
+exclude ruff.toml

Makefile

@@ -1,23 +1,23 @@
-.PHONY: tests lint clean build install dev docs
+.PHONY: install dev tests lint docs clean build
+
+install:
+	pip install .
+
+dev:
+	pip install -e .
 
 tests:
 	pytest -s -x -vv tests/test*.py
 
 lint:
 	pre-commit run --all-files
 
+docs:
+	# sphinx-apidoc --implicit-namespaces -f -o docs/source/ pytket
+	sphinx-build -M html docs/source/ docs/build/
+
 clean:
 	rm -rf *.egg-info dist build docs/build
 
 build: clean
-	python -m build --sdist -n
-
-install:
-	pip install .
-
-dev:
-	pip install -e .
-
-docs:
-	# sphinx-apidoc -f -o docs/source/ pytket
-	sphinx-build -M html docs/source/ docs/build/
+	python -m build --sdist --wheel -n

README.md

@@ -1,11 +1,48 @@
 # pytket-phir
 
+[![PyPI version](https://badge.fury.io/py/pytket-phir.svg)](https://badge.fury.io/py/pytket-phir)
+[![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11-blue.svg)](https://img.shields.io/badge/python-3.10%2C%203.11-blue.svg)
+
 PHIR stands for _[PECOS](https://github.com/PECOS-packages/PECOS) High-level Intermediate Representation_.
 See [PHIR specification](https://github.com/CQCL/phir/blob/main/spec.md) for more.
 
+`pytket-phir` is a circuit analyzer and translator from [pytket](https://tket.quantinuum.com/api-docs/index.html) to PHIR.
+
+Also included is the CLI tool `phirc` that takes QASM programs as input and emulates them using PECOS.
+
+## Prerequisites
+
+Python >=3.10
+
 ## Installation
 
-To install the project, clone the repository and run:
+Just issue `pip install pytket-phir` to obtain the latest stable release.
+
+## phirc CLI
+
+The package includes a tool for emulating QASM files from the command line using PECOS.
+
+PECOS needs to be installed using `pip install .[phirc]` for the CLI to work.
+
+```sh
+❯ phirc -h
+usage: phirc [-h] [-m {H1-1,H1-2}] [-v] qasm_files [qasm_files ...]
+
+Emulates QASM program execution via PECOS
+
+positional arguments:
+  qasm_files            One or more QASM files to emulate
+
+options:
+  -h, --help            show this help message and exit
+  -m {H1-1,H1-2}, --machine {H1-1,H1-2}
+                        machine name, H1-1 by default
+  -v, --version         show program's version number and exit
+```
+
+## Development
+
+Clone the repository and run:
 
 ```sh
 python -m venv .venv
@@ -15,7 +52,7 @@ pip install -r requirements.txt
 pre-commit install
 ```
 
-Then install the project using:
+Then, install the project using:
 
 ```sh
 pip install -e .
@@ -25,4 +62,4 @@ See `Makefile` for other useful commands.
 
 ## Testing
 
-Just issue `pytest` from the root directory.
+Issue `pytest` from the root directory.

docs/source/conf.py

@@ -1,3 +1,11 @@
+##############################################################################
+#
+# Copyright (c) 2023 Quantinuum LLC All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+#
+##############################################################################
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -7,24 +15,24 @@
 # add these directories to sys.path here.
 import pathlib
 import sys
+from importlib.metadata import version as get_version
 
-sys.path.insert(0, pathlib.Path("../../pytket").resolve().as_posix())
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "pytket.phir"
-project_copyright = "2023, Quantinuum"
-author = "Quantinuum"
-release = "0.0.1"
+project = "pytket-phir"
+project_copyright = "2023, Quantinuum LLC"
+author = "Quantinuum LLC"
+release: str = ".".join(get_version("pytket-phir").split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
 ]
 
@@ -34,4 +42,4 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"

docs/source/index.rst

@@ -12,6 +12,21 @@ PHIR stands for `PECOS <https://github.com/PECOS-packages/PECOS>`__
 specification <https://github.com/CQCL/phir/blob/main/spec.md>`__
 for more.
 
+``pytket-phir`` is a circuit analyzer and translator from
+`pytket <https://tket.quantinuum.com/api-docs/index.html>`__ to PHIR.
+
+Also included is the CLI tool ``phirc`` that takes QASM programs as
+input and emulates them using PECOS.
+
+Installation
+------------
+
+To install pytket-phir, simply run:
+
+.. code-block:: bash
+
+   pip install pytket-phir
+
 Indices and tables
 ==================
 

docs/source/modules.rst

@@ -1,7 +1,7 @@
-pytket
-======
+pytket.phir
+===========
 
 .. toctree::
    :maxdepth: 4
 
-   phir
+   pytket.phir