docs: Add compiler API docs

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Build and publish docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+  # Temporary: Run on PR to test the CI
+  pull_request:
+    branches:
+      - main
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-publish:
+    name: Build and publish docs
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    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
+          cd ..
+
+      - name: Setup pages.
+        uses: actions/configure-pages@v2
+      - name: Upload artifact.
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./docs/build/
+      - 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/custom-class-template.rst

@@ -0,0 +1,38 @@
+..
+   Custom class template to make sphinx-autosummary list the full API doc after
+   the summary. See https://github.com/sphinx-doc/sphinx/issues/7912
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% 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/custom-module-template.rst

@@ -0,0 +1,70 @@
+..
+   Custom module template to make sphinx-autosummary list the full API doc after
+   the summary. See https://github.com/sphinx-doc/sphinx/issues/7912
+
+{{ fullname | 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:
+      :template: custom-class-template.rst
+      :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:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api-docs/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+# See https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+project = "Guppy Compiler"
+copyright = "2024, Quantinuum"
+author = "Quantinuum"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "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/guppy",
+    "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),
+}

docs/api-docs/index.rst

@@ -0,0 +1,22 @@
+Guppy Compiler API Documentation
+================================
+
+This is the API documentation for the Guppy compiler.
+
+Note that 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: custom-module-template.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