Sphinx tools for OpenQASM

This repository provides the Python package openqasm-sphinx, which provides a Sphinx extension for documentation OpenQASM 2 and 3 code.

The documentation is hosted at https://openqasm.com/openqasm-sphinx.

Installation

Install the latest release of openqasm-sphinx package from pip:

pip install openqasm-sphinx

This will automatically install all the dependencies as well (Sphinx, for example) if they are not already installed.

Use

To activate the extension add openqasm_sphinx to your extensions list in your Sphinx conf.py file, such as:

project = "My Project"
author = "Me"
version = "1.0"

extensions = [
    "openqasm_sphinx",
]

There is no need to import the extension; Sphinx will handle this automatically.

Document a gate by doing:

.. oq:gate:: my_gate(θ) a, b

    This is my gate.

and later insert a cross-reference to it in inline text with:

For more information, see :oq:gate:`my_gate`.

If you are set primary_domain = "oq" in your Sphinx configuration, you can drop the oq prefixes.

For more complete usage information, see the rendered documentation.

Developing

If you're looking to contribute to this project, please first read our contributing guidelines.

Set up your development environment by installing the development requirements with pip:

pip install -r requirements-dev.txt tox

This installs a few more packages than the dependencies of the package at runtime.

After the development requirements are installed, you can install an editable version of the package with

pip install -e .

After this, any changes you make to the library code will immediately be present when you open a new Python interpreter session, or build a Sphinx project that depends on this project.

License

This project is licensed under version 2.0 of the Apache License. This is a Qiskit project.