Pytorch-lightning: Broken [Source] links in docs

[dedeswim]

📚 Documentation

Hello, I was browsing the docs, and out of curiosity, I wanted to check the source for LightningModule, and so I clicked on the [Source] link of the forward method. The link, however, sends to https://github.com/PyTorchLightning/PyTorch-Lightning/blob/pytorch_lightning/core/lightning/LightningModule.py, which is not right, as the repo name is "pytorch-lightning".

I am not familiar with Sphinx, but I checked the docs and the conf file, and I think that the reason can be found here:

https://github.com/PyTorchLightning/pytorch-lightning/blob/ee4eae884b137054e10f21a44f0d1d427405e310/docs/source/conf.py#L59-L71

Since github-repo is set to project, which is, indeed, PyTorch-Lightning, as in the broken link.

If someone more familiar with Sphinx can confirm this, I'd be glad to submit a PR to fix this.

[github-actions[bot]]

Hi! thanks for your contribution!, great first issue!

[Borda]

@awaelchli mind have look? 🐰

[ananyahjha93]

@dedeswim so the reason you pointed out is not exactly why a wrong link is being generated for LightningModule.

https://github.com/PyTorchLightning/pytorch-lightning/blob/master/docs/source/conf.py#L347

The function linkcode_resolve generates the 'source' links in the doc and that is giving out the wrong link for LightningModule. If you see the link generated for say TrainResult class, it links to the master branch and the exact line number for the methods, which is not the case here.

[Borda]

btw, need to keep compatibility with tagged releases as well as with master...

[dedeswim]

Hi, thank you @ananyahjha93 for the explanation!

I indeed realized that the link should go to "pytorch_lightning/core/lightning.py", instead of "pytorch_lightning/core/lightning/LightningModule.py".

Interestingly, the 0.8.5 version of the docs redirects to the right link (the one above), whereas the "0.9.0", "latest" and "stable" versions (which are the same version, right?) don't work.

[Borda]

ok, then we may have the wrong path in docs, is it only this case or all docs have wrong links?

[dedeswim]

I tried with all the other classes under the "Python API" section of the bar on the right in the docs and it looks like this is the only one broken

[Borda]

ok, then it is nothing with linkcode_resolve but just wrong link in docs, mind send a PR fix
https://github.com/PyTorchLightning/pytorch-lightning/blob/4d98419bb84e06c06aaee0a86530e322e24f6d11/pytorch_lightning/core/lightning.py#L136

[dedeswim]

I'd be happy to, but I am not sure about how to fix this. Where is the path to the source defined? Isn't it generated by linkcode_resolve?

[ananyahjha93]

@Borda others are correct, LightningModule is the only one that seems broken.

[awaelchli]

it looks like this is because in the .rst docs we refer to the methods with autofunction instead of automethod. changing to automethod solves the link issue, but breaks formatting of docs, need to figure out how to properly use it.

[ydcjeff]

@Borda or @awaelchli is there a specific reason using linkcode extension?
if not, shall we use this extension https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html?
this creates _modules folder for source code and link to that folder. PyTorch is using this also.

It also solves this issue using automethod, autofunction won't work just like @awaelchli comment.
I discovered that PyTorch docs doesn't refer to source code for methods, so we need to add some css to the forked theme.

Here's the tried output:
It doesn't show self which is pretty normal I think, just like methods of other classes.

[awaelchli]

@ydcjeff nice, could you make a draft PR so we can try it out?

[ydcjeff]

@awaelchli with viewcode extension?
sure, I can

[awaelchli]

so you say it's a two step fix.

1. replace linkcode with viewcode, which solves the problem with linked source code, but we lose methods source code
2. add the custom css to the theme so we have methods properly linked

if it can consistently link all modules, classes, methods and functions, I think this is what we want.

[ydcjeff]

Yes, pytorch sphinx theme doesn't include css for directly linking methods.
So, we need to add it. I think viewcode works with all modules, classes, methods and functions.

But i will try with all to make sure it works and i will draft a PR

[Borda]

just testing and sure if it is a better way as before it linked to GitHub source and you simply create a perm link...