Add tutorials to examples

rscircus commented 5 months ago

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: https://github.com/qiboteam/qibolab/issues/828

Todo:

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

[x] add calibration examples
[x] add circuits examples
[x] add compiler examples
[x] add instrument examples
[x] add lab examples
[x] 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 commented 5 months ago

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 commented 5 months ago

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

That was the idea. :)

rscircus commented 5 months ago

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

rscircus commented 4 months ago

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

rscircus commented 4 months ago

@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 commented 4 months ago

@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 commented 3 months ago

Rebased on top of main - https://github.com/qiboteam/qibolab/commit/a514441f7c020b190c7871df90d6892392d0b4da

rscircus commented 3 months ago

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 commented 3 weeks ago

Rebase onto qiboteam:main

qiboteam / qibolab