Add tutorials to examples

[rscircus]

The docs of this project contain examples. However, these examples have a few missing dependencies and other tiny errata. To fix these this PR proposes to:

• add the examples in the tutorial
• source the shown examples in the tutorial from these examples
• such that the tutorials contain less tiny mistakes
• allow a 'newbie' to get started quicker

This PR partially addresses issue #802.

Discussion:

How to deal with testcode/testoutput in sphinx? It fails right now as described in: #828

Todo:

After rebase: Update example scripts to current state of docs.

• add calibration examples
• add circuits examples
• add compiler examples
• add instrument examples
• add lab examples
• add pulse examples
• provide brief description of each tutorial as module docstring

Testing:

• diff against docs generated by main

Checklist:

• Tests are passing.
• Coverage does not decrease.
• Documentation is updated.
• Reviewers confirm new code works as expected.

[alecandido]

Thank you very much @rscircus, I just took a quick look, but I will take a deeper one as soon as possible.

I added a tiny comment for the time being, and I have a further one: could you provide a (even brief) description of each tutorial?
You could even use a module docstring for this (just a docstring starting at line 1)

[alecandido]

source the shown examples in the tutorial from these examples

I guess you mean something like this?
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude

such that the tutorials contain less tiny mistakes

This in principle should be prevented by doctest, since they are already running in the CI (but for sure there is something broken)

allow a 'newbie' to get started quicker

Instead, this could be an interesting point of view: self-contained scripts might be helpful for beginners :)

[rscircus]

Instead, this could be an interesting point of view: self-contained scripts might be helpful for beginners :)

That was the idea. :)

[rscircus]

I'll continue working on this at the weekend! :)

[rscircus]

Sorry for the delay here. The past two weeks have been very busy.

[rscircus]

@alecandido - used literalincludes to add the examples shown in the tutorial. Maybe we have to think about having two examples folders now. Anyway, I already saw the advantage that the pre-commit hook started to modify the code examples I updated from the current docs. ☺️

[alecandido]

@alecandido - used literalincludes to add the examples shown in the tutorial. Maybe we have to think about having two examples folders now. Anyway, I already saw the advantage that the pre-commit hook started to modify the code examples I updated from the current docs. ☺️

Thanks @rscircus, that is definitely good!

Embedding languages in other languages is always messy, because they get closer to arbitrary strings. IDEs are now providing support, but it is never as good as for the native one, and similarly concerning tools.

Whenever this will be merged, we could even propagate to the other Qibo projects.

[rscircus]

Rebased on top of main - a514441

[rscircus]

Not sure how to deal with some of the testcode, which @stavros11 also mentioned in #828. Multiple options are available. I'd suggest to discuss this.

[rscircus]

Rebase onto qiboteam:main