docs: Add compiler API docs (#194)

Co-authored-by: Agustín Borgna <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Build and publish docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued.
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build docs.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run sccache-cache
+        uses: mozilla-actions/[email protected]
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python '3.10'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: "poetry"
+      - name: Install Guppy
+        run: poetry install --with docs
+      - name: Build docs
+        run: |
+          cd docs
+          ./build.sh
+      - name: Upload artifact.
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build/
+
+  publish:
+    name: Publish docs.
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy to GitHub Pages.
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/_static/custom.css

@@ -0,0 +1,38 @@
+.wy-side-nav-search,
+.wy-nav-top {
+    background: #5A46BE;
+}
+
+.wy-grid-for-nav,
+.wy-body-for-nav,
+.wy-nav-side,
+.wy-side-scroll,
+.wy-menu,
+.wy-menu-vertical {
+    background-color: #FFFFFF;
+}
+
+.wy-menu-vertical a:hover {
+    background-color: #d9d9d9;
+}
+
+.btn-link:visited,
+.btn-link,
+a:visited,
+.a.reference.external,
+.a.reference.internal,
+.wy-menu-vertical a,
+.wy-menu-vertical li,
+.wy-menu-vertical ul,
+.span.pre,
+.sig-param,
+.std.std-ref,
+
+
+html[data-theme=light] {
+    --pst-color-inline-code: rgb(199, 37, 78) !important;
+}
+
+.sig-name {
+    font-size: 1.25rem;
+}

docs/api-docs/.gitignore

@@ -0,0 +1,3 @@
+_autosummary
+_build
+generated

docs/api-docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/api-docs/_templates/autosummary/class.rst

@@ -0,0 +1,37 @@
+..
+   Custom class template to make sphinx-autosummary list the full API doc after
+   the summary. See https://github.com/sphinx-doc/sphinx/issues/7912
+
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/api-docs/_templates/autosummary/module.rst

@@ -0,0 +1,68 @@
+..
+   Custom module template to make sphinx-autosummary list the full API doc after
+   the summary. See https://github.com/sphinx-doc/sphinx/issues/7912
+
+{{ name | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api-docs/conf.py

@@ -0,0 +1,105 @@
+# Configuration file for the Sphinx documentation builder.
+# See https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import inspect
+import guppylang
+from types import GenericAlias, UnionType
+
+project = "Guppy Compiler"
+copyright = "2024, Quantinuum"
+author = "Quantinuum"
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+]
+
+html_theme = "sphinx_book_theme"
+
+html_title = "Guppy compiler development docs"
+
+html_theme_options = {
+    "repository_url": "https://github.com/CQCL/guppylang",
+    "use_repository_button": True,
+    "navigation_with_keys": True,
+    "logo": {
+        "image_light": "_static/Quantinuum_logo_black.png",
+        "image_dark": "_static/Quantinuum_logo_white.png",
+    },
+}
+
+html_static_path = ["../_static"]
+html_css_files = ["custom.css"]
+
+autosummary_generate = True
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+
+
+# add_module_names = False
+
+
+def _is_type_alias(x):
+    """Checks if an object is a type alias.
+
+    Note that this function only catches non-trivial aliases like `IntList = list[int]`
+    or `Number = int | float`. Aliases like `MyAlias = int` cannot easily be detected.
+    """
+    return isinstance(x, GenericAlias | UnionType)
+
+
+def _find_aliases(module):
+    """Finds all type aliases defined in a guppylang module and its submodules.
+
+    Returns a mapping from alias names to the  module in which they are defined.
+    """
+    aliases = {}
+    for name, x in inspect.getmembers(module):
+        if _is_type_alias(x):
+            aliases[name] = module
+        if inspect.ismodule(x) and x.__name__.startswith("guppylang."):
+            aliases |= _find_aliases(x)
+    return aliases
+
+
+# Generate a mapping from type aliases to their qualified name to ensure that autodoc
+# doesn't unfold them
+_aliases = _find_aliases(guppylang)
+autodoc_type_aliases = {
+    alias: f"~{module.__name__}.{alias}" for alias, module in _aliases.items()
+}
+
+# Also create a set of all qualified alias names
+_qualified_aliases = {
+    f"{module.__name__}.{alias}" for alias, module in _aliases.items()
+}
+
+
+def resolve_type_aliases(app, env, node, contnode):
+    """Resolve :class: references to our type aliases as :data: instead.
+
+    When trying to resolve references in type annotations, Sphinx only looks at :class:
+    nodes since types are typically classes. However, type aliases are :data: so are
+    not found by default. See https://github.com/sphinx-doc/sphinx/issues/10785
+    """
+    if (
+        node["refdomain"] == "py"
+        and node["reftype"] == "class"
+        and node["reftarget"] in _qualified_aliases
+    ):
+        ref = app.env.get_domain("py").resolve_xref(
+            env, node["refdoc"], app.builder, "data", node["reftarget"], node, contnode
+        )
+        return ref
+
+def setup(app):
+    app.connect("missing-reference", resolve_type_aliases)

docs/api-docs/index.rst

@@ -0,0 +1,23 @@
+Guppy Compiler API Documentation
+================================
+
+This is the API documentation for the Guppy compiler.
+
+.. note::
+   This page is designed for contributors to the Guppy compiler, not users of the language.
+   See TODO for the language documentation.
+
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/module.rst
+   :recursive:
+
+   guppylang
+
+
+Indices and tables
+~~~~~~~~~~~~~~~~~~
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/build.sh

@@ -0,0 +1,5 @@
+mkdir build
+
+touch build/.nojekyll  # Disable jekyll to keep files starting with underscores
+
+poetry run sphinx-build -b html ./api-docs ./build/api-docs

guppylang/tys/ty.py

@@ -423,15 +423,21 @@ def transform(self, transformer: Transformer) -> "Type":
         )
 
 
-# We define the `Type` type as a union of all `TypeBase` subclasses defined above. This
-# models an algebraic data type and enables exhaustiveness checking in pattern matches
-# etc.
-# Note that this might become obsolete in case the `@sealed` decorator is added:
-#  * https://peps.python.org/pep-0622/#sealed-classes-as-algebraic-data-types
-#  * https://github.com/johnthagen/sealed-typing-pep
+#: The type of parametrized Guppy types.
 ParametrizedType: TypeAlias = FunctionType | TupleType | SumType | OpaqueType
+
+#: The type of Guppy types.
+#:
+#: This is a type alias for a union of all Guppy types defined in this module. This
+#: models an algebraic data type and enables exhaustiveness checking in pattern matches
+#: etc.
+#:
+#: This might become obsolete in case the @sealed decorator is added:
+#:   * https://peps.python.org/pep-0622/#sealed-classes-as-algebraic-data-types
+#:   * https://github.com/johnthagen/sealed-typing-pep
 Type: TypeAlias = BoundTypeVar | ExistentialTypeVar | NoneType | ParametrizedType
 
+#: An immutable row of Guppy types.
 TypeRow: TypeAlias = Sequence[Type]