docs(hugr-py): docstrings for builder (#1231)

first commit just copies in the docs building infrastructure from guppy,
the rest add docstrings by file. There are some minor refactor commits
towards the end that I couldn't untangle from the docs.

Closes #1214 

To build docs:

```bash
cd hugr-py
poetry install --with=docs
cd docs
./build.sh
open build/api-docs/index.html
```

---------

Co-authored-by: Alan Lawrence <[email protected]>
Co-authored-by: Alec Edgington <[email protected]>

hugr-py/docs/.gitignore

@@ -0,0 +1 @@
+build

hugr-py/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;
+}

hugr-py/docs/api-docs/.gitignore

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

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

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

hugr-py/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 %}

hugr-py/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 %}

hugr-py/docs/api-docs/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.  # noqa: INP001
+# See https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+project = "HUGR Python"
+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 = "HUGR python package API documentation."
+
+html_theme_options = {
+    "repository_url": "https://github.com/CQCL/hugr",
+    "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", "conftest.py"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+
+html_show_sourcelink = False

hugr-py/docs/api-docs/index.rst

@@ -0,0 +1,20 @@
+HUGR Python API Documentation
+==================================
+
+This is the API documentation for the HUGR Python package.
+
+
+.. autosummary::
+   :toctree: generated
+   :template: autosummary/module.rst
+   :recursive:
+
+   hugr
+
+
+Indices and tables
+~~~~~~~~~~~~~~~~~~
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

hugr-py/docs/build.sh

@@ -0,0 +1,7 @@
+#! /bin/bash
+
+mkdir build
+
+touch build/.nojekyll  # Disable jekyll to keep files starting with underscores
+
+sphinx-build -b html ./api-docs ./build/api-docs