[DOC] Improvement of documentation

[Mildophin]

This MR adds a folder named 'examples' that is filled with python code snippets representing parts of code we want to display to the users when they start using pasqal-cloud and send their first batch of jobs.

The updated code snippet in the readme is not visible in this MR because the link has to target a commit or branch name and I put the dev branch to makes sure it doesn't break when I will close this MR and also to have the snippet displayed updated automatically (we still have to change the last line number if we add or remove code).

Also, this MR is to have only one source of truth for all the tutorials linked to pasqal-cloud, so we only have to embed the code of these examples instead of updating each tutorial one by one.

Edit: https://github.com/pasqal-io/pasqal-cloud/pull/104#issuecomment-1740932760

[awennersteen]

I like the idea!

Would it be much effort to put the rest of the code snippets in the README into the same format?

Are you sure it wouldn't be possible to make the links relative somehow? We do have a master branch (although we don't use it much :( ) for example.

[Mildophin]

I like the idea!

Would it be much effort to put the rest of the code snippets in the README into the same format?

Are you sure it wouldn't be possible to make the links relative somehow? We do have a master branch (although we don't use it much :( ) for example. @awennersteen

It's really hard, tbh i'm having headaches of how difficult it is to embed python code from another file in markdown files, I'm currently thinking they are trying to prevent it for a reason. The best solution I see for now is switching to readthedoc (sphinx) to embed snippets properly. Exactly like they did for Pulser.

For the branch master, well, not used, so not considered haha

[Mildophin]

After giving it enough thought, I am dropping the idea of a unique source of truth for now. I think it will be more useful later when we will build a more detailed documentation for pasqal cloud, for now I think that the simplest way for developers to update the documentation is to do it by hand.

I will change this MR to only update the code examples in the readme. Then I will set up a checklist for each MR on pasqal cloud, telling everyone what to check before merging it but also what to do after it is merged.

[Mildophin]

To help you reviewing it, here is the link to the readme file: https://github.com/pasqal-io/pasqal-cloud/blob/mv/improvement-of-documentation-examples/README.md

[Mildophin]

I added a pull request in this MR to make sure we don't forget any point while working on pasqal-cloud. Feel free to correct me if I forgot something or if my english is broken.

[Mildophin]

Updated.

Link for the readme: https://github.com/pasqal-io/pasqal-cloud/blob/mv/improvement-of-documentation-examples/README.md

Link for the PR template: https://github.com/pasqal-io/pasqal-cloud/blob/mv/improvement-of-documentation-examples/.github/pull_request_template.md

[Mildophin]

@MatthieuMoreau0 I do agree it is probably easier for users when it is in one big block but after discussing with @oliver-gordon I think that it is better this way as there are different ways of authenticating, we can target different emulators or the QPU, there are many options. Also explanations shouldn't be code comments. However I do agree later on it would be nice to implement a whole bloc of code that we can copy + a detailed documentation explaining all the possibilities pasqal-cloud can provide (readthedoc?).