Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add TKET tips page #364

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

docs: add TKET tips page #364

wants to merge 12 commits into from

Conversation

CalMacCQ
Copy link
Collaborator

@CalMacCQ CalMacCQ commented Aug 13, 2024

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

@CalMacCQ CalMacCQ marked this pull request as draft August 13, 2024 13:46
@CalMacCQ CalMacCQ marked this pull request as ready for review August 23, 2024 00:49
@willsimmons1465
Copy link
Contributor

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.

Copy link
Contributor

@willsimmons1465 willsimmons1465 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add FAQs/TKET TIPS section to user guide
2 participants