Add links to docstrings everywhere in the documentation

[HaroldErbin]

This is a minor request, but I think it could simplify browsing the documentation: in most places in the tutorials, the names of classes, functions, etc., which are cited don't have a link to the corresponding page/anchor. Such names appear in red. In few cases, the name is in black and links to the API reference.

This is helpful to directly access the full signature and description when the arguments are not obvious given the context, or get more information quickly without having to search for it (especially helpful for beginners who will learn through the tutorials and may not yet be accustomed to the organization of the code).

I think this should be possible with Sphinx cross-referencing, though it would require some work to convert all backticks to the appropriate ReST tags and I am not sure how this integrates with notebook includes.

[HGSilveri]

Hey @HaroldErbin , thanks for the suggestion!
I definitely agree that having proper cross-referencing everywhere would have been much better.
The issue is exactly what you suspect though - it is very inconvenient to do this in a notebook as it forces one to not use markdown on the specific cell and instead make it a "raw ReST cell". This often comes with its own drawbacks, so it is ultimately a trade off.

[HaroldErbin]

I had not realized first that it could be a problem since the tutorial Results and Observables does include links to the Results class, but looking at the source I see that it's indeed a rst cell.

Maybe another alternative to make it work would be to use MyST, which is a modified flavor of markdown to work with Sphinx? In particular, it seems that Sphinx can use both ReST and MyST parsers at the same time. I did not use it myself so I cannot give feedback on its usage, but it looked promising (I was interested in using it first because the math environments are simpler in markdown, but also because I already take all my notes in markdown).

[HGSilveri]

Maybe another alternative to make it work would be to use MyST, which is a modified flavor of markdown to work with Sphinx? In particular, it seems that Sphinx can use both ReST and MyST parsers at the same time. I did not use it myself so I cannot give feedback on its usage, but it looked promising (I was interested in using it first because the math environments are simpler in markdown, but also because I already take all my notes in markdown).

We looked into this and we even wrote some docs pages in MyST, so on those it should be possible to use the Sphinx cross-referencing. However, we never managed to combine notebooks with MyST, so notebooks remained in pure markdown (outside of the raw rst cells).

[HaroldErbin]

I see, thanks for the explanations. It's really weird that they don't allow for this. In that case the best is indeed keeping markdown and hoping one day they will add this feature to Sphinx.