https://github.com/openqasm/openqasm-sphinx
Sphinx extension for documenting OpenQASM
https://github.com/openqasm/openqasm-sphinx
documentation openqasm quantum-programming-language sphinx
Last synced: 10 months ago
JSON representation
Sphinx extension for documenting OpenQASM
- Host: GitHub
- URL: https://github.com/openqasm/openqasm-sphinx
- Owner: openqasm
- License: apache-2.0
- Created: 2024-04-08T15:45:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-09T17:09:03.000Z (over 1 year ago)
- Last Synced: 2025-01-14T20:37:03.098Z (11 months ago)
- Topics: documentation, openqasm, quantum-programming-language, sphinx
- Language: Python
- Homepage: https://openqasm.com/openqasm-sphinx
- Size: 130 KB
- Stars: 0
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Sphinx tools for OpenQASM
[](https://opensource.org/licenses/Apache-2.0)[](https://github.com/openqasm/openqasm-sphinx/releases)[](https://pypi.org/project/openqasm-sphinx/)
This repository provides the Python package `openqasm-sphinx`, which provides a [Sphinx extension](https://www.sphinx-doc.org) 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:
```bash
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:
```python
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:
```rst
.. oq:gate:: my_gate(θ) a, b
This is my gate.
```
and later insert a cross-reference to it in inline text with:
```rst
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](https://openqasm.com/openqasm-sphinx).
## Developing
If you're looking to contribute to this project, please first read [our contributing guidelines](CONTRIBUTING.md).
Set up your development environment by installing the development requirements with pip:
```bash
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
```bash
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](LICENSE).
This is a Qiskit project.