Skip to content

/ matplotlib

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Have [Source] in api docs link to github #20557

Open
ianhi opened this issue Jun 30, 2021 · 8 comments
Open

Have [Source] in api docs link to github #20557

ianhi opened this issue Jun 30, 2021 · 8 comments
Labels
Documentation Good first issue

Comments

@ianhi
Copy link
Contributor

@ianhi ianhi commented Jun 30, 2021

Problem

The source link in the docs:
image

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.
@param-thakker
Copy link

@param-thakker param-thakker commented 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
Copy link
Contributor Author

@ianhi ianhi commented 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
Copy link
Member

@timhoffm timhoffm commented Jun 30, 2021 •
edited

👍 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
Copy link
Member

@tacaswell tacaswell commented 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
Copy link
Member

@timhoffm timhoffm commented 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
Copy link
Contributor

@jklymak jklymak commented 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
Copy link
Contributor

@rajpratyush rajpratyush commented Jul 4, 2021

is this issue still open for work?
@timhoffm
Copy link
Member

@timhoffm timhoffm commented Jul 4, 2021

Yes. You‘re welcome to pick it up.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Good first issue
Projects
None yet
Milestone
No milestone
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
@tacaswell @jklymak @timhoffm @ianhi @param-thakker @rajpratyush