docs: use theming submodule, update docs build and linking #1609

CalMacCQ · 2024-10-07T12:45:26Z

Description

Updating the API docs build to use pytket-docs-theming as a submodule. This is already in place for the extensions.

Also no longer using a pypi version of pytket to build the docs in C.I. (rather a develop wheel). fixes #1517

This means using a shared conf.py file so I've deleted that along with the _static dir.

I've also updated the display.rst page to use the MyST-NB library for showing code snippets. This ensures visual consistency with other parts of the TKET docs.

I've cleaned up some of the crosslinking to the extension packages in extensions.md.

Also updated all links to point to docs.quantinuum.com/tket rather than tket.quantinuum.com

Related issues

closes #1517

…n the source code that it's written down.

CalMacCQ · 2024-10-14T14:13:19Z

nix-support/pytket.nix

 self: super:
 let
-  config_contents = builtins.readFile ../pytket/docs/conf.py;
-  versions =
-    builtins.match ''.*release *= *["']([^"']+)["'].*'' config_contents;


Changed by Jake in c3f417b

CalMacCQ · 2024-10-14T14:14:21Z

pytket/docs/extensions.md

+## Types of Backend
+
+- **QPUs** - These are real quantum computers that return shots based results. E.g the [QuantinuumBackend](inv:#*.QuantinuumBackend) .
+- **Cloud Access** - Cloud backends allow pytket to interface with cloud platforms to access additional QPUs and simulators. E.g [BraketBackend](inv:#*.BraketBackend) .


Updated some of these links to use robust intersphinx linking. Will do the rest in another PR.

cqc-alec

There are a lot of error in the logs from the docs build here. Are these expected?

cqc-alec · 2024-10-14T14:31:42Z

pytket/docs/circuit.rst

-   display.rst
+   display.md


Are you planning to change the others to markdown as well?

Not in a rush to do that.

I updated display.md because I wanted to use the MyST-NB library to show the code snippets on that page (consistent styling for the rest of the docs)

I updated the extensions index page to markdown because I wanted to use the more robust linking syntax where I don't have to use the full URL.

There are automated tools for doing the conversion so I could possibly update the other files in a subsequent PR.

cqc-alec · 2024-10-14T14:33:28Z

pytket/docs/circuit_class.rst

@@ -338,7 +338,7 @@ condition on a specified set of bit values.)

   .. Note:: For adding boxes to a circuit the :py:meth:`Circuit.add_gate` method is sufficient to append any :py:class:`OpType` to a :py:class:`Circuit`.

-   .. jupyter-input::
+   ::


What effect does this have?

None really. It just doesn't use the jupyter sphinx package. Removed this dependency and will use MyST-NB in most places. See display.md

It'll still show as a code snippet with just ::

CalMacCQ · 2024-10-14T15:00:26Z

There are a lot of error in the logs from the docs build here. Are these expected?

Ah this is a problem. Thanks for pointing this out - the pytket installation doesn't work as expected. The C.I. build was still passing but there are still some problems as it allows warnings.

EDIT: mostly resolved. The warnings were resolved by ensuring that pytket was installed (I've used the editable wheel to build the docs)

Still a couple more warnings to squash in addition to the expected ones. EDIT: these relate to the links on the extensions page but I've verified that these still work.

…/shared_theme_sm

CalMacCQ · 2024-10-15T09:32:55Z

.github/workflows/build_and_test.yml

@@ -312,12 +312,11 @@ jobs:
      if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
      timeout-minutes: 20
      run: |
-        pip install poetry==1.6.1
+        pip install poetry==1.8.1
+        poetry config virtualenvs.create false


Here I'm not using the default .venv with poetry and instead using the editable wheel of pytket installed earlier in the workflow

CalMacCQ · 2024-10-15T09:39:57Z

pytket/docs/extensions.md

+
+[IBMQEmulatorBackend](inv:#*.IBMQEmulatorBackend) - A backend which uses the [AerBackend](inv:#*.AerBackend) to emulate the behavior of IBMQBackend.
+
+[QuantinuumBackend](inv:#*.QuantinuumBackend)


Note that there are some additional build warnings given by this new syntax. I think these are due to the fact that QuantinuumBackend (and other backends) don't have a unique import path.

The links do work however and I've ran a link checker over these pages to fix any broken links.

I'll make an issue to fix the warnings. The output is quite cluttered already

I can just see one warning that might be important, but it can be fixed in another PR (or this one if you prefer):

/home/runner/work/tket/tket/pytket/pytket/utils/operators.py:docstring of pytket.utils.QubitPauliOperator.all_qubits:7: WARNING: Definition list ends without a blank line; unexpected unindent.

I'd rather fix that last warning in a follow up PR if thats okay. Not immediately sure what the matter is.

CalMacCQ · 2024-10-15T10:04:23Z

pytket/docs/extensions.md

+
+pytket-aqt <https://cqcl.github.io/pytket-aqt/api/index.html>
+pytket-azure <https://docs.quantinuum.com/tket/extensions/pytket-azure>
+pytket-braket <https://docs.quantinuum.com/tket/extensions/pytket-braket>


Unfortunately the linking syntax doesn't straightforwardly work with these TOCtree links which is annoying. I'll have to come back to this in another PR.

CalMacCQ · 2024-10-15T10:46:07Z

.github/workflows/build_and_test.yml

    - name: Upload artifact
      if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
      uses: actions/upload-artifact@v4
      with:
        name: pytket_docs
-        path: pytket/docs/build/html/
+        path: pytket/docs/build/


This is so that the artifact goes to the right place

cqc-alec · 2024-10-15T11:47:29Z

pytket/docs/backends.rst


-There are several `example notebooks <https://tket.quantinuum.com/examples>`_ on pytket :py:class:`Backend`\s. If you are interested in developing your own :py:class:`Backend` or pytket extension then see the `creating backends <https://tket.quantinuum.com/user-guide/examples/backends/creating_backends.html>`_ tutorial.
+There are several example notebooks on pytket :py:class:`~pytket.backends.Backend`\s. If you are interested in developing your own :py:class:`Backend` or pytket extension then see the `creating backends <https://docs.quantinuum.com/tket/user-guide/examples/backends/creating_backends.html>`_ tutorial.


If we're not including the link to the example notebooks I suggest just removing the first sentence.

This was actually an invalid link. However I agree I should remove the setnence as well.

removed 523aa2a

cqc-alec · 2024-10-15T11:52:22Z

pytket/docs/index.rst

@@ -48,7 +48,7 @@ To install the ``pytket-quantinuum`` package use the following command.
    pip install pytket-quantinuum

 The extensions supported by tket are described
-`here <https://tket.quantinuum.com/api-docs/extensions>`_.
+`here <extensions.html>`_.


In getting_started.rst this is linked ad <extensions.md>, but here as <extensions.html>. Which is preferable?

Gone with .html for both for consistency -> 4e94b72

cqc-alec · 2024-10-15T11:54:23Z

pytket/docs/install.rst

@@ -28,7 +28,7 @@ Building TKET from source

 TKET can be built from source by compiling the C++. This is now possible on MacOS, Windows and Linux (including ARM Linux).

-For instructions on how to do this see the `tket repository README <https://github.com/CQCL/tket#how-to-build-tket-and-pytket>`_. 
+For instructions on how to do this see the `tket repository README <https://github.com/CQCL/tket?tab=readme-ov-file#how-to-build-tket-and-pytket>`_. 


I don't understand what this change to the URL does. Is it necessary? (The old URL seems to work for me.)

Link checker was complaining about this for some reason. However as you point out it worked fine so I'll revert back to the orginal link.

used the original -> 6859a1e

cqc-alec · 2024-10-15T12:12:10Z

.github/workflows/build_and_test.yml

@@ -312,18 +312,17 @@ jobs:
      if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
      timeout-minutes: 20
      run: |
-        pip install poetry==1.6.1
+        pip install poetry==1.8.1


Is it important that it be exactly this version of poetry or can we just assume the latest version will work?

I updated it so that I could use package-mode=false in pyproject.toml this clarifies that we're only using poetry to install the docs dependencies. We are not using it for package management here.

Seems this isn't available in 1.6.1.

So we can probably make it >=1.8.1? Less likely to have dependency conflicts in the future if we do that.

Good idea, updated dd03ddd

cqc-alec · 2024-10-15T12:31:47Z

pytket/docs/extensions.md

+
+[IBMQEmulatorBackend](inv:#*.IBMQEmulatorBackend) - A backend which uses the [AerBackend](inv:#*.AerBackend) to emulate the behavior of IBMQBackend.
+
+[QuantinuumBackend](inv:#*.QuantinuumBackend)


I can just see one warning that might be important, but it can be fixed in another PR (or this one if you prefer):

/home/runner/work/tket/tket/pytket/pytket/utils/operators.py:docstring of pytket.utils.QubitPauliOperator.all_qubits:7: WARNING: Definition list ends without a blank line; unexpected unindent.

@johnchildren

* Bump cachix/install-nix-action from 29 to 30 (#1606) Bumps [cachix/install-nix-action](https://github.com/cachix/install-nix-action) from 29 to 30. - [Release notes](https://github.com/cachix/install-nix-action/releases) - [Commits](cachix/install-nix-action@v29...v30) --- updated-dependencies: - dependency-name: cachix/install-nix-action dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fix initialization of subcircuit in `GuidedPauliSimp` implementation (#1607) * Update docs and changelog for 1.33.1 release. (#1612) * fix: update wasm functions to accept `WasmModuleHandler` (#1613) * Update macos CI runners (#1616) * Fix default value of wire_comments. (#1618) * docs: use theming submodule, update docs build and linking (#1609) * remove quantinuum-sphinx * add pytket-docs-theming submodule * delete _static and conf.py * ignore jupyter cache * use myst-nb for code cells * use latest theming commit * ignore any generated .ipynb files * add myst_nb dependency * remove jupyter sphinx and autodoc annotations dependencies * add build docs script * fix formatting of display.md * update docs build in build and test workflow * remove pypi pytket installation * Hardcode pytket version in flake.nix, as there is no longer a place in the source code that it's written down. * ignore jupyter execute * use latest pytket-docs-theming submodule * update extensions links * update sidebar heading for extensions * update pypi page links * update README links * replace remaining docs links * use latest theming commit * use package-mode=false for poetry * install a develop wheel of pytket * try to fix poetry issue * use poetry without .venv in C.I. * run docs build from correct directory * use latest docs theming update * fix up some extensions links * fix some broken links found by checker * link to H-Series docs * fix two more links * fix typo * latest theming (again) * fix artifact path * use extensions.html * use original README link * remove backends sentance * use >= for poetry --------- Co-authored-by: Jake Arkinstall <[email protected]> * Support Python 3.13 (#1620) * Bugfix/circuit renderer (#1614) * add default min width/height to circuit renderer config * update docs * changelog * Don't try to install pytket[ZX] with Python 3.13. (#1627) * `ClExprOp` and friends (#1628) * Set MacOS deployment target to 12 for x86. (#1633) * Drop support for MacOS 12 (#1634) * Updated nixpkgs. Added custom mypy build. (#1636) * Updated nixpkgs. Added custom mypy build (required version isn't in nixpkgs) * Used overrideAttrs on nixpkgs' mypy rather than a new derivation as per @johnchildren's suggestion * Refactor greedy pauli simp (#1611) * Initial refactor * Refactor node types * Move nodes definition into a new file * Refactor synthesis * Cleanup * More refactoring * Refactor pauli graph converters * Initial implementation of GPGraph * Migrate to GPGraph * Ignore global phase * Add supports for conditional gates * Add support for classical ops * flatten_registers should only rename qubits and bits * Replace unsigned with Bit * Revert "Replace unsigned with Bit" This reverts commit 9e9a2fd. * Manually check if qubits and bits can be flattened since ``is_simple()`` doesn't work with wasm * Consistent enum names * Add support for mid-circuit measurement * Rename variables * Add support for resets * Update docstrings * Update pass predicate * Add more tests * bump tket version * Add changelog entry * Fix docs errors * bump tket version * Remove unused headers * bump tket version in pytket * uncomment lines * remove consts in SQ_CLIFF_DAGGER * Merging conditionals * Revert "Merging conditionals" This reverts commit f5138f1. * Optimise conditional handling * remove ConditionalPauliRotation * Remove clifford reduction and pass parameters when synthesis conditionals * Seeded tie breaking * Add limits to the search space * Allowing ZZPhase gates * update binder and serialisation * Add test for ops handling in python * add note for AC node cost * bump tket version * update changelog * fix changelog format * add missing prams in docstrings * cast size_t to unsigned * remove nondeterminism from test * Remove more nondeterminism * regen stubs * Add debug info * Revert "Add debug info" This reverts commit e5030e2. * Replace implicit wire swaps in optimised conditional circuits * re-organise changelog * Bump tket version * fix bug in sign correction * Add more tests * Bump version and update changelog for 1.34.0 release (#1637) --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alec Edgington <[email protected]> Co-authored-by: Kartik Singhal <[email protected]> Co-authored-by: Jake Arkinstall <[email protected]> Co-authored-by: Tiffany Duneau <[email protected]> Co-authored-by: yao-cqc <[email protected]>

CalMacCQ added 13 commits October 7, 2024 13:15

remove quantinuum-sphinx

ee7cb3a

add pytket-docs-theming submodule

6e972e7

delete _static and conf.py

798faea

ignore jupyter cache

f93f734

use myst-nb for code cells

931ed9b

use latest theming commit

89b9732

ignore any generated .ipynb files

e82b523

add myst_nb dependency

31eeb2b

remove jupyter sphinx and autodoc annotations dependencies

1eaf505

add build docs script

807f343

fix formatting of display.md

a959362

update docs build in build and test workflow

20e9deb

remove pypi pytket installation

f9f6515

CalMacCQ changed the title ~~docs: use pytket-docs-theming submodule~~ docs: use pytket-docs-theming submodule, update sphinx build Oct 7, 2024

Hardcode pytket version in flake.nix, as there is no longer a place i…

c3f417b

…n the source code that it's written down.

CalMacCQ changed the title ~~docs: use pytket-docs-theming submodule, update sphinx build~~ docs: use pytket-docs-theming submodule,update build and linking Oct 11, 2024

CalMacCQ added 8 commits October 11, 2024 16:07

ignore jupyter execute

2485c69

use latest pytket-docs-theming submodule

56409ba

update extensions links

bd10232

update sidebar heading for extensions

30ed6f6

update pypi page links

f8f8418

update README links

877f55a

replace remaining docs links

d769ac2

use latest theming commit

b86afb7

CalMacCQ commented Oct 14, 2024

View reviewed changes

CalMacCQ requested a review from cqc-alec October 14, 2024 14:14

resolve merge conflicts

b584d03

cqc-alec reviewed Oct 14, 2024

View reviewed changes

CalMacCQ added 6 commits October 14, 2024 18:01

run docs build from correct directory

05f9244

Merge branch 'main' into docs/shared_theme_sm

e6f68fa

use latest docs theming update

b0fc072

Merge branch 'docs/shared_theme_sm' of github.com:CQCL/tket into docs…

656c128

…/shared_theme_sm

fix up some extensions links

e078066

fix some broken links found by checker

dafebb8

CalMacCQ commented Oct 15, 2024

View reviewed changes

link to H-Series docs

e6f7b78

CalMacCQ commented Oct 15, 2024

View reviewed changes

CalMacCQ requested a review from cqc-alec October 15, 2024 09:43

CalMacCQ commented Oct 15, 2024

View reviewed changes

CalMacCQ added 4 commits October 15, 2024 11:10

fix two more links

d77a5f8

fix typo

fc94c94

latest theming (again)

c64476c

fix artifact path

a2cf8aa

CalMacCQ commented Oct 15, 2024

View reviewed changes

CalMacCQ requested review from cqc-alec and removed request for cqc-alec October 15, 2024 12:29

cqc-alec reviewed Oct 15, 2024

View reviewed changes

CalMacCQ added 4 commits October 15, 2024 13:42

use extensions.html

4e94b72

use original README link

6859a1e

remove backends sentance

523aa2a

use >= for poetry

dd03ddd

CalMacCQ requested a review from cqc-alec October 15, 2024 13:09

cqc-alec approved these changes Oct 15, 2024

View reviewed changes

CalMacCQ merged commit 0ec32d2 into main Oct 15, 2024
32 checks passed

CalMacCQ deleted the docs/shared_theme_sm branch October 15, 2024 13:12

This was referenced Oct 15, 2024

docs: update docmain for #1609 #1623

Merged

docs: update docs build instructions #1625

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: use theming submodule, update docs build and linking #1609

docs: use theming submodule, update docs build and linking #1609

CalMacCQ commented Oct 7, 2024 •

edited

Loading

CalMacCQ Oct 14, 2024 •

edited

Loading

CalMacCQ Oct 14, 2024

cqc-alec left a comment

cqc-alec Oct 14, 2024

CalMacCQ Oct 15, 2024 •

edited

Loading

cqc-alec Oct 14, 2024

CalMacCQ Oct 14, 2024 •

edited

Loading

CalMacCQ commented Oct 14, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024

CalMacCQ Oct 15, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024 •

edited

Loading

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024

CalMacCQ Oct 15, 2024

cqc-alec Oct 15, 2024


		[IBMQEmulatorBackend](inv:#.IBMQEmulatorBackend) - A backend which uses the [AerBackend](inv:#.AerBackend) to emulate the behavior of IBMQBackend.

		[QuantinuumBackend](inv:#*.QuantinuumBackend)


		There are several `example notebooks <https://tket.quantinuum.com/examples>`_ on pytket :py:class:`Backend`\s. If you are interested in developing your own :py:class:`Backend` or pytket extension then see the `creating backends <https://tket.quantinuum.com/user-guide/examples/backends/creating_backends.html>`_ tutorial.
		There are several example notebooks on pytket :py:class:`~pytket.backends.Backend`\s. If you are interested in developing your own :py:class:`Backend` or pytket extension then see the `creating backends <https://docs.quantinuum.com/tket/user-guide/examples/backends/creating_backends.html>`_ tutorial.

docs: use theming submodule, update docs build and linking #1609

docs: use theming submodule, update docs build and linking #1609

Conversation

CalMacCQ commented Oct 7, 2024 • edited Loading

Description

Related issues

CalMacCQ Oct 14, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cqc-alec left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CalMacCQ Oct 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CalMacCQ Oct 14, 2024 • edited Loading

Choose a reason for hiding this comment

CalMacCQ commented Oct 14, 2024 • edited Loading

CalMacCQ Oct 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CalMacCQ Oct 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CalMacCQ Oct 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CalMacCQ commented Oct 7, 2024 •

edited

Loading

CalMacCQ Oct 14, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024 •

edited

Loading

CalMacCQ Oct 14, 2024 •

edited

Loading

CalMacCQ commented Oct 14, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024 •

edited

Loading

CalMacCQ Oct 15, 2024 •

edited

Loading