search

CQCL / pytket-docs

User manual and example notebooks for the pytket quantum computing toolkit
https://tket.quantinuum.com/user-guide/
Apache License 2.0
328 stars 92 forks source link

docs: add TKET tips page #364

Open CalMacCQ opened 1 month ago

CalMacCQ commented 1 month ago

Description

Adding the TKET support tips to the public docs as I had a few requests to do this. I also think its quite nice to have a section of the docs which is mostly Q&A. There are 6 informal entries so far and can add more over time. This should probably replace https://tket.quantinuum.com/api-docs/faqs.html which doesn't have much content anyway.

Had some fun playing around with pure markdown notebooks using the myst-nb library. This is the same library I use to generate the example notebook html pages.

Screenshot 2024-08-23 at 01 47 47

Note that there is a bit of visual inconsistency between the manual and examples code cells at present. This is because they are built with two different libraries. I think it should be doable to port the manual to myst-nb without loss of functionality. Personally I much prefer the look of the MyST-nb cells and markdown is easy to write. There are also automated tools for .rst -> .md conversion which we could use.

Added the tips as a manual page for now. If you think theres a better place, let me know.

Screenshot 2024-08-23 at 01 46 38

Related issues

closes #362

willsimmons1465 commented 3 weeks ago

This looks like a nice thing to provide. A short one/two sentence header at the start of the page to set the expectations of what kinds of questions would go on here, and how to request questions that aren't on here would not go amiss.

As for where it is located in navigation, I think I would prefer it take the place of the existing TKET FAQs section in both function and location. In theory, the manual should be a comprehensive tour through all features so the answers to these questions should be available in prose somewhere in there, whereas this fits much more easily into the API docs side of things where a user would go to try and solve a specific task rather than learning about a broad topic in the user guide. Just an opinion though, so I'm open to hearing arguments for keeping it with the manual.

I also agree that the MyST-nb code cells are slightly better aesthetically. So long as they provide the same functionality regarding the ability to test the code cells in CI (including to skip individual cells that are expensive/require device access) then I agree that getting things consistent is a good one-off task to get done at some point.