Guppy Documentation

This repository contains documentation for the Guppy programming language.

Contents

• The Guppy language guide
• The Guppy landing page
• The API documentation for the guppylang package
• FAQs, changelog and migration guides
• The guppylang example notebooks (included via the guppylang submodule)

The Sphinx docs are written in MyST markdown and rendered with the myst-nb library. This variant of markdown supports code cells which are executed at docs build time. See the section on text-based notebooks. The docs are styled with the quantinuum-sphinx theme.

For information on how the landing page is built, see the landing page README.

Testing in C.I.

The following checks are run when a pull request is opened.

• Spell checking - spell checking is done using the typos crate.
• The sphinx docs build is tested. This includes all code snippets and example notebooks. If a code snippet throws an error, this will fail the docs build.
• Link checking (using the sphinx-linkcheck builder) - All links in the sphinx directory are tested. Broken links will cause the C.I. checks to fail.
• (currently disabled) Sphinx coverage checks using sphinx.ext.coverage - check that all of the public guppylang API is documented.

Building the docs locally

Requirements:

• The just command runner
• Sphinx docs -> uv

See the devenv.nix file.

First clone the repository making sure to checkout the guppylang submodule.

git clone [email protected]:CQCL/guppy-docs.git --recurse-submodules

Alternatively you can update the submodules if you have already cloned the repository.

git submodule update --init

Next run the build with just build. This builds both the Sphinx docs and the landing page

just build

The built html page can be served locally with:

just serve

To clean all of the files generated by the sphinx build:

just cleanup

To run the build in "debug" mode:

just build-debug

Followed by

just serve-debug

Building the docs in debug mode with just build-debug allows sphinx warnings whereas just build treats these warnings as errors. Debug mode is useful for debugging issues with the executed Guppy code in the docs.

To check the API docs coverage run:

just coverage

To check all of the links in the Sphinx docs run:

just link-check