Repository navigation
Have [Source] in api docs link to github #20557
Description
Problem
The source link in the docs:
links to the matplotlib source on the website. This is ok, but subsequent navigation of the code is more frustrating than on github. For example I can't figure out how to the get to the folder containing https://matplotlib.org/stable/_modules/matplotlib/widgets.html#AxesWidget
Suggested Improvement
Have these be appropriate permalinks to github. This is what scipy does, see: https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.cdist.html#scipy.spatial.distance.cdist
I think the downside is in the archaeology sense that github is perhap more impermanent than the matplotlib website.
Activity
param-thakker commentedon Jun 30, 2021
Hi @ianhi , Can I work on this? I'm a first time contributor. Also, where can I find this source link in the codebase?
ianhi commentedon Jun 30, 2021
Hi @param-thakker anyone is welcome to work on any issue so feel free to have a go at it. That said this issue probably deserves some discussion from other people before being implemented as it's not clear that everyone would view it as an improvement.
timhoffm commentedon Jun 30, 2021
👍 On this. Those code pages are massive in our code base (to an extend that we've deactivated upload of these pages for CI) and the code is on github anyway. I don't think impermanence of github is a practical issue. The only downside would be that you might loose the docs source link for old versions if GitHub goes away and we move to something else. That's as unlikely as it's bearable.
I propose to discuss this on the dev call tomorrow.
@param-thakker You're welcome to work on this, once we have decided this is something we want.
The source links are generated by sphinx. One can modify this behavior through the [sphinx.ext.linkcode](plugin https://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html).
See also https://github.com/scipy/scipy/blob/b8bdbbf112413e9a8f5e209fc05d3b8927718b28/doc/source/conf.py#L427 for the solution in SciPy.
tacaswell commentedon Jul 1, 2021
There is also some re-hosting of our docs on internal (air-gapped) networks or just on laptops so there are some use cases where having all of the links be internal is nice.
timhoffm commentedon Jul 1, 2021
It was decided on the dev call, that we want to move to linking to github. @param-thakker You are welcome to pick this up.
jklymak commentedon Jul 1, 2021
Note we also would like it so there was a switch on the sphinx config to build with the rendered source so folks could optionally build the old way, if feasible
rajpratyush commentedon Jul 4, 2021
is this issue still open for work?
timhoffm commentedon Jul 4, 2021
Yes. You‘re welcome to pick it up.
chachaleo commentedon Jul 22, 2021
Is this issue still open?
timhoffm commentedon Jul 22, 2021
This is still open, but with a proposed solution in #20673.
dmatos2012 commentedon Aug 8, 2021
Merged in #20673