API Reference Rework

[HGSilveri]

• Setup a new structure for the API reference
• Document all public symbols in pulser-simulation
• Add temporary API reference for pulser_pasqal too

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[a-corni]

It's really looking good ! I have a small issue, it seems to me the classes BaseDevice and BaseRegister are no longer in the documentation and as a user that would annoy me a lot - I feel like something is being hidden from me, even though all the properties of BaseRegister/BaseDevice are being displayed in Register/Register3D or Device/VirtualDevice

[a-corni]

Actually, it's all the ABC classes that disappeared. It depends on who we are targetting with the API documentation, but I thought that it would be developpers, that I think would like to see these classes. If it's people that just use pulser, then the current state makes sense, because it only displays the useful classes.

[HGSilveri]

It's really looking good ! I have a small issue, it seems to me the classes BaseDevice and BaseRegister are no longer in the documentation and as a user that would annoy me a lot - I feel like something is being hidden from me, even though all the properties of BaseRegister/BaseDevice are being displayed in Register/Register3D or Device/VirtualDevice

Ok, this is a discussion we have to have.
These classes are never supposed to be initialized (nor subclassed by a third-party like Backend) so, to me, they are not part of the API - it would even be misleading to include them, as it may signal that they are to be used directly. I made sure that the inherited arguments are all shown so technically, nothing useful is being hidden.
Of course, it worries me that you (and potentially others) would be "annoyed a lot" by this, so I'm definitely willing to reconsider this decision.
What do you think about this @ferrulli1pasqal ?

Btw, I'll be the first to admit that I might not be entirely consistent with this selection criteria for what to expose and what to hide. In general, I just went with what made sense to me.

[ferrulli1pasqal]

I still have issue in properly visualising the pages -.- so my answer will be quite general.

I guess @a-corni you make a right point and I believe that the answer should come from answering the following question: which use cases would be covered by exposing the ABC classes?

If the ABC classes are there to let people create their own version of a NA QPU, then I would prefer to have them not highlighted. This to me is consistent with the principle we adopted last October which is to make Pulser closer to Pasqal QPU and on a secondary level also a tool to program any NA qpu.
If instead, ABC can be relevant then maybe we should reconsider this choice.

A third way maybe is to group them together? A section of ABC classes, would this be possible?

[a-corni]

I agree with both of you, the API documentation should only expose the interface for the user. It is not an issue not to expose the ABC classes because the code is open-source and because the documentation exposes all the functions inherited from the ABC classes.