cff-version: 1.2.0

message: "If you use the labscript suite to control your experiment or perform analysis, please cite the article from preferred-citation and the software itself."

title: The labscript suite

authors:

- name: "The labscript-suite development team"

abstract: "A powerful and extensible framework for experiment composition, control, execution, and analysis that implements repeated, parameterised, hardware-time experiments."

keywords:

- research

- "experiment composition"

- "experiment control"

- "experiment analysis"

- "quantum science"

- "quantum engineering"

- hardware-timed

license: BSD-2-Clause

repository-code: "https://github.com/labscript-suite"

url: "https://docs.labscriptsuite.org/en/latest/"

references:

- type: software

authors:

- family-names: Billington

given-names: Chris J.

title: zprocess

repository-code: "https://github.com/chrisjbillington/zprocess"

- type: software

authors:

- family-names: Starkey

given-names: Philip

- family-names: Billington

given-names: Chris J.

title: qtutils

repository-code: "https://github.com/philipstarkey/qtutils"

url: "https://qtutils.readthedocs.io/en/stable/"

- type: software

authors:

- family-names: Billington

given-names: Chris J.

title: spinapi

repository-code: "https://github.com/chrisjbillington/spinapi/"

- type: software

authors:

- family-names: Cladé

given-names: Pierre

title: PyDAQmx

repository-code: "https://github.com/clade/PyDAQmx"

url: "https://pythonhosted.org/PyDAQmx/"

- type: software

authors:

- family-names: Johnson

given-names: Peter

- family-names: Billington

given-names: Chris J.

title: pynivision

repository-code: "https://github.com/chrisjbillington/pynivision"

- type: phdthesis

authors:

- family-names: Billington

given-names: Chris J.

title: "State-dependent forces in cold quantum gases"

school: "Monash University"

year: 2018

doi: 10.26180/5bd68acaf0696

scope: "Chapter 4 provides an excellent, detailed overview of the labscript-suite"

- type: phdthesis

authors:

- family-names: Starkey

given-names: Philip

title: "A software framework for control and automation of precisely timed experiments"

school: "Monash University"

year: 2019

doi: 10.26180/5d1db8ffe29ef

scope: "This provides an in-depth description of the labscript-suite, circa 2019"

preferred-citation:

type: article

title: A scripted control system for autonomous hardware-timed experiments

authors:

- family-names: Starkey

given-names: Philip T.

- family-names: Billington

given-names: Christopher J.

orcid: "https://orcid.org/0000-0002-8067-6400"

- family-names: Johnstone

given-names: Shaun P.

orcid: "https://orcid.org/0000-0002-4704-9552"

- family-names: Jasperse

given-names: M.

- family-names: Helmerson

given-names: K.

- family-names: Turner

given-names: Lincoln D.

- family-names: Anderson

given-names: Russell P.

orcid: "https://orcid.org/0000-0002-4495-7926"

doi: "10.1063/1.4817213"

journal: "Review of Scientific Instruments"

month: 8

year: 2013

start: 085111 # page number

issue: 84

Building the *labscript suite* docs

The **labscript-suite** documentation is hosted online at `<https://docs.labscriptsuite.org/en/latest/>`_.

It is composed from documentation for each module of the **labscript-suite**.

If you desire to build the documentation for a module locally, either for off-line usage or to test changes to the documentation, you will need to apply extra configuration beyond a normal installation.

This is because our documentation building pipeline relies on `sphinx <https://www.sphinx-doc.org/en/master/>`_, which introspects documentation from inline docstrings from the source code.

This introspection process requires that the code to be documented is importable and the necessary `sphinx` dependencies are installed.

The below sections describe how to configure your environment for building docs as well as some guidance for writing and contributing documentation.

.. toctree::

:maxdepth: 2

building_docs/docs_install

building_docs/docs_build

building_docs/docs_writing

building_docs/docs_comitting

building_docs/docs_resources

building_docs/docs_minutia

Building the Docs

The **labscript-suite** documentation is built one repository at a time.

To build the documentation for a single repository:

#. Activate the environment where the **labscript-suite** and sphinx dependencies are installed.

#. Change directories to the `docs` subfolder of the repository.

#. Run the appropriate `make` command, described below.

Assuming the appropriate dependencies are installed, the documentation will be built and placed in a subfolder of `docs/build` corresponding to the build command used.

html

The web-based documentation, which is what is hosted at `<https://docs.labscriptsuite.org/en/latest/>`_ by Read the Docs, is built locally using the command

.. code-block:: bash

The home page is found at `docs/build/html/index.html`.

Repeated calls of this (and the other) build commands will introspect which source files have changed and only update the corresponding build outputs.

Note that the build on Read the Docs uses the closely related `make dirhtml` command.

This build command organizes the html documentation in a way suitable for web hosting.

For locally inspecting the documentation, the `make html` command is preferred to preserve normal inter-page links.

.. note::

Some cross-referencing used in the markdown files is not cross-compatible between the `html` and `dirthtml` build commands.

When using markdown source files, please ensure cross-references actually work when built on Read the Docs.

latexpdf

Building the pdf documentation is a bit more complicated than the other builds.

Normally it would be done by running the command

.. code-block:: bash

This would create latex source files which are automatically compiled using an existing, local installation of latex.

The latex compilation requires `perl` and the `latexmk` latex package.

It also requires a great many other latex dependencies.

Successfully building the pdf documentation locally is made easier if your latex installation can install dependencies as required.

Unfortunately, this simple build command :ref:`does not succeed <building_docs/docs_minutia:latexpdf local builds>` for **labscript-suite** documentation.

To build the pdf docs locally, you will need to instead build using the `make latex` command followed by the latex compiling command used on Read the Docs.

.. code-block:: bash

This command is run from within the `docs/build/latex` directory where the `latexmkrc` file resides.

epub

This builds the documentation in the EPUB format, for use with e-readers.

It is built using the command

.. code-block:: bash

clean

This make target will clean the entire `build` directory.

It ensures that a fresh build can be made.

It is helpful when stale build files are interfering with new changes or you wish to see the :ref:`coverage <building_docs/docs_writing:docstring coverage>`.

The command is

.. code-block:: bash

Committing Docs

Committing documentation updates/fixes is an important way to contribute to the **labscript-suite** community.

Increasing the amount of technical details in the documentation that are necessary to use the suite but are not obvious from the source is of particular value.

The mechanics of committing documentation to a **labscript-suite** component is nearly identical to committing general code updates/fixes:

:doc:`a pull request needs to be created </contributing>`.

The main difference is that documentation changes necessitate checking the read the docs builds to confirm what was desired actually makes it into the on-line documentation as intended.

Making a PR

The general steps for creating the PR are outlined in :doc:`here <contributing>`.

When making PRs with documentation changes, a few extra checks are required.

In particular, it is a good idea to locally build the documentation as described :doc:`here <docs_build>`.

If you cannot build locally, the docs will be built automatically for your PR by Read the Docs and can be viewed there (described below).

Checking the RTD Builds

When a PR is created or updated with new commits, an automated check of the documentation build is performed by Read the Docs.

The result of this build can be viewed online by looking at the details of the automated checks.

If the build is completed, this link will take you directly to the home page of your built documentation.

If the build is still in progress, this link will take you to the build progress which shows the commands being run and their outputs.

If you wish to see this progress after the build succeeds, you can find it by clicking the bottom left corner of the Read the Docs page.

This will bring up a small window pane.

Selecting 'Builds' will bring up the build logs for all of the online builds.

If the build did not succeed, this link takes you to the build progress stage with the failing command and corresponding outputs displayed.

Note that Read the Docs will only build the html documentation for a pull request.

When the pull request is merged, Read the Docs will build the html documentation again, as well as downloadable pdf and epub versions.

These downloads are available via the 'Downloads' link next to the 'Builds' link in the bottom left corner pop-up pane on-line.

Setting up the environment

The build environment generally requires a full **labscript-suite** installation, with a few extra dependencies.

The simplest method is to use the environment of an existing, functioning installation and install the build dependencies.

If you do not want to install the docs dependencies into a working environment of an experiment,

or wish the develop docs on a system that does not control an experiment,

you can create a new environment.

.. note::

These instructions assume you have generally followed the installation instructions for a developer **labscript-suite** installation,

using either the :doc:`pip </installation/developer-pypi>` or :doc:`anaconda </installation/developer-anaconda>` method.

Install build dependencies

If you have an existing, functioning environment for using the **labscript-suite**, you can configure it to build docs by simply installing the docs dependencies found in the `setup.cfg` file of each repository.

For a functioning **labscript** environment, the only additional dependencies should be `sphinx`, `sphinx-rtd-theme`, `recommonmark`, and `m2r`.

The versions pinned in the `setup.cfg` file will be the versions of these packages that are used by Read the Docs when building the documentation.

In order to get an accurate reproduction of what the online docs look like, you should ensure the versions you install match the pins.

Once these dependencies are installed in your **labscript** environment, you are ready to build the docs.

Using a cloned environment

If you have an existing, functioning **labscript** environment, but do not want to install the many build dependecies into it, you can instead build the docs using a cloned copy of the functioning environment.

You clone a conda enviroment using

.. code-block:: bash

Here we clone an existing `labscript` conda environment into a new environment `labscript-sphinx`.

This new enviroment will be an exact duplicate of the original at the time of cloning.

Changes in one environment will not affect the other.

Once the new environment is created, you can activate it then install the dependencies for the docs as described above.

When using this method, both enviroments will use the same installation of the **labscript-suite**.

Using a new environment

If you desire to build the docs on a computer without an existing **labscript-suite** installation, you will need to first install the suite using one of the developer installation methods described :doc:`here </installation/index>`.

Once installed, follow the directions above to install the docs dependencies into the environment.

.. note::

The normal installation steps to create a labscript profile and the launcher shortcuts should not be necessary when only building docs.

This installation method should also be used if you desire to develop documentation in local repositories separate from an existing installation (i.e. having two environments using different installations of the **labscript-suite**).

This can be desirable if you want to avoid docs dependencies in a function environment *and* want to isolate local changes for a functioning experiment from documentation developement.

Minutia

Here is a list of minor details that come up when dealing with our docs that are not well documented in the Sphinx docs or are very unique to our project.

autosummary can't find a module

When you get an error while building the docs stating autosummary could not find a module, it could be due to one of two things:

1. The module actually cannot be found, due to a typo in the `autosummary` command.

2. The much more likely reason, the module is actually found, but cannot be imported.

In order to see the actual error to diagnose the problem properly, temporarily remove that module from the `autosummary` directive and do an explicit `automodule` directive.

Once the import error is fixed, you can move the module back into the `autosummary` directive.

*labscript-devices* API

Unlike the rest of the **labscript-suite**, **labscript-devices** does NOT use recursive `autosummary` calls to generate the API documentation.

This means that, unlike other modules, adding a new device to **labscript-devices** will NOT automatically be captured in the docs build.

When adding a new device, you are expected to make a top-level rst document that implements the necessary `autodoc` calls to document the device.

.. note::

In all modules, adding a sub-module at the top-level likely will not be automatically caught either.

It will need to be added to the relevant `autosummary` directive manually.

latexPDF local builds

Local builds of the latexPDF version of the documentation will not work using the standard `make latexpdf` command.

This is because the **labscript-suite** uses svg figure icons that latex cannot process.

This build **does** work on RTD because they do not use the `latexpdf` make target, but instead call `latexmk` with customized options that ignore these little errors.

In order to build the PDF documentation locally, you will need to use the same call as RTD uses.

Note that the RTD latex build is fairly stable, if really ugly, so long as the html docs build.

That said, if there is an error unique to the latex build, discovering its origin can be very difficult since the build process has to ignore errors to complete normally anyway.

One specific error already encounted is when an API documentated value is too long for latex to parse as a single line (a raw bitmap image saved as a class attribute).

This specific error can be overcome by instructing sphinx to not publish the value in the docs using the `:meta hide-value:` rst key for the offending object.

intersphinx references won't link

Using intersphinx links to reference documentation in other packages (or even the same package) can be tricky.

This is because the exact convention for referring to things is not guaranteed between projects.

The best way to determine the exact reference label to use is to introspect the intersphinx object inventory for that project (the `objects.inv` file).

This can be done by calling, for example,

.. code-block:: shell

See `this <https://stackoverflow.com/a/30981554>`__ SO post for many details.

This file is typically stored at the top level directory of a project, but not always.

If the above command does not work to obtain the objects inventory for online docs, it can be run on a local copy of the file without issue.

Obtaining the file for online published docs amounts to guessing the correct location and pointing your browser there.

To run the introspection locally, use

.. code-block:: shell

In this call, we redirect the output to a text file for easier inspection.