Add documentation

docs/conf.py

@@ -1,14 +1,20 @@
-project = 'OpenQASM Pygments Tools'
-copyright = '2022, OpenQASM contributors'
+# SPDX-License-Identifier: Apache-2.0
+
+# pylint: disable=invalid-name
+
+import openqasm_sphinx
+
+project = 'OpenQASM Sphinx extension'
+project_copyright = '2024, OpenQASM contributors'
 author = 'OpenQASM contributors'
-version = "0.1.2"
+version = openqasm_sphinx.__version__
+
+primary_domain = "rst"
 
 extensions = [
-    "sphinx.ext.autodoc",
+    "openqasm_sphinx",
+    "sphinxcontrib.katex",
 ]
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# Document the docstring for the class and the __init__ method together.
-autoclass_content = "both"
-
 html_theme = 'alabaster'

docs/index.rst

@@ -1,7 +1,63 @@
 Sphinx Tools for OpenQASM
 =========================
 
-.. module:: openqasm_sphinx
-
 This project is a Sphinx extension that adds an OpenQASM domain for Sphinx.
 The domain is called ``oq``, and can be used to document both OpenQASM 2 and 3.
+
+To use this domain, make sure this package is installed in your docs build, and add ``openqasm_sphinx`` to your ``extensions`` list in your ``conf.py`` file, such as:
+
+.. code-block:: python
+
+   project = "My Project"
+   author = "Me"
+   version = "1.0"
+
+   extensions = [
+       "openqasm_sphinx",
+   ]
+
+If your documentation project is primarily (or only) about documenting OpenQASM gates, you can set `the default domain for documentation <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain>`__ by setting ``primary_domain`` in your ``conf.py`` file, such as:
+
+.. code-block:: python
+
+   extension = ["openqasm_sphinx"]
+   primary_domain = "oq"
+
+The project defines a directive for documenting OpenQASM gates.
+
+.. directive:: .. gate:: signature
+
+   Document an OpenQASM gate with the given signature.
+   The body of the directive is the documentation content.
+
+   Gates defined with this directive are cross-referenced using the :role:`gate` role.
+
+   The signature should look like it would in OpenQASM, for example:
+
+   .. code-block:: rst
+
+      .. oq:gate:: cx a, b
+
+         The controlled-X gate.
+
+      .. oq:gate:: rz(θ) a
+
+         A rotation by :math:`\theta` around the :math:`Z` axis.
+
+   renders as
+
+   .. oq:gate:: cx a, b
+
+      The controlled-X gate.
+
+   .. oq:gate:: rz(θ) a
+
+      A rotation by :math:`\theta` around the :math:`Z` axis.
+
+   .. versionadded:: 0.1.0
+
+.. role:: gate
+
+   The cross-referencing role for the :dir:`gate` directive.
+
+   .. versionadded:: 0.1.0

requirements-dev.txt

@@ -1,4 +1,5 @@
 Sphinx>=5.0.0
+sphinxcontrib-katex~=0.9.9
 astroid~=3.1.0
 pylint~=3.1.0
 black~=24.1