Help projects use sphinx.ext.linkcode so that source code links to GitHub

[javabster]

Many Qiskit projects use the viewcode sphinx extension which adds a [SOURCE] button to function and class definitions. This extension essentially generates a modules subfolder in the _build directory when a sphinx build is run, and creates new html files that pull in the source code. We have heard feedback from users that instead it would be preferable to redirect to the classes and functions in GitHub (this also has the benefits of helping out contributors find where a specific python class/function lives). It would be great if we could engineer our own solution in the sphinx theme that works similarly to the viewcode extension, but instead adds a "view on GitHub" button to each class and function.

ReadTheDocs has existing guidance on how to add "Edit source" links to pages using sphinx, and we used to implement something similar in the old breadcrumbs component, although it was broken most of the time because of the specific way that the github urls need to be pieced together.

[woodsp-ibm]

A couple of comments.

• The source page now does give the fully qualified module path - though maybe you need to find the repo manually for it to apply that path.
• The source page as-is has links back to the docs so if you scroll through the source there and see some function of interest, but the docstring is unformatted there with math expressions etc and harder to read, you can click back to the docs. Will that bi-directionality get lost - I assume it would.
• The source that the docs would have to refer to is stored away in various stable branches for the versions. A contributor would be dealing with the main branch. Hopefully having them interact with code on stable branches may well be confusing. And of course the code is live out there on the latest stable version with bug fixes being backported ahead of release - what is shipped and what you are running (which is captured in the html when the release is done at present) may not be quite the same as you are looking at in stable. Releases are tagged there so maybe more precision is possible.

[javabster]

Thanks Steve this is useful context! We were going back and forth on some of these considerations already and we don't have a clear path forward right now. It would be good to see if there is a way to enhance what the viewcode extension does 🤔 And you're right one of the biggest challenges is the actual source code lives in different subdirectories that differ across different packages, so finding a github url format that would work for all users of the theme may be tricky...

[Eric-Arellano]

The right way to do this is using sphinx.ext.linkcode rather than sphinx.ext.viewcode. Numpy has interesting code that will link to the correct place in GitHub: https://github.com/numpy/numpy/blob/v1.25.0/doc/source/conf.py#L441

We should try to adapt that code to Qiskit projects. We should expose a function in qiskit_sphinx_theme's Python code that you can set up in your conf.py so that you don't have to copy all that wild logic across every project.

[Eric-Arellano]

There are no examples of this in the wild:

• Switch Qiskit, Runtime, and Provider to have more precise source code links documentation#517
• Use sphinx.ext.linkcode for more precise source code links qiskit-ibm-runtime#1431

For most projects, I suspect it's better to use viewcode though because it's simpler config. See discussion in qiskit-community/qiskit-algorithms#170.

I don't think there's anything the qiskit-sphinx-theme should do to generalize this mechanism.