Repository: Lightning-AI/pytorch-lightning

Issue:
Broken [Source] links in docs
## 📚 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.



Discussion:
Hi! thanks for your contribution!, great first issue!
@awaelchli mind have look? 🐰 
@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.
btw, need to keep compatibility with tagged releases as well as with master...
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.
ok, then we may have the wrong path in docs, is it only this case or all docs have wrong links?
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
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
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`?
@Borda others are correct, LightningModule is the only one that seems broken.
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.
@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.

![Screen Shot 2020-09-14 at 22 57 57](https://user-images.githubusercontent.com/32727188/93113155-d7af8b80-f6de-11ea-9840-7026948f0250.png)

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

@awaelchli with `viewcode` extension?
sure, I can
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.
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

Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -69,7 +69,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'PyTorch-Lightning'
+project = 'PyTorch Lightning'
 copyright = pytorch_lightning.__copyright__
 author = pytorch_lightning.__author__
 
@@ -78,10 +78,6 @@
 # The full version, including alpha/beta/rc tags
 release = pytorch_lightning.__version__
 
-# Options for the linkcode extension
-# ----------------------------------
-github_user = 'PyTorchLightning'
-github_repo = project
 
 # -- General configuration ---------------------------------------------------
 
@@ -100,7 +96,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.linkcode',
+    'sphinx.ext.viewcode',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
     'sphinx.ext.imgmath',
@@ -267,7 +263,7 @@
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'torch': ('https://pytorch.org/docs/stable/', None),
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
     'PIL': ('https://pillow.readthedocs.io/en/stable/', None),
 }
 
@@ -323,51 +319,12 @@ def package_list_from_file(file):
 ]
 autodoc_mock_imports = MOCK_PACKAGES + MOCK_MANUAL_PACKAGES
 
-
-# Resolve function
-# This function is used to populate the (source) links in the API
-def linkcode_resolve(domain, info):
-    def find_source():
-        # try to find the file and line number, based on code from numpy:
-        # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286
-        obj = sys.modules[info['module']]
-        for part in info['fullname'].split('.'):
-            obj = getattr(obj, part)
-        fname = inspect.getsourcefile(obj)
-        # https://github.com/rtfd/readthedocs.org/issues/5735
-        if any([s in fname for s in ('readthedocs', 'rtfd', 'checkouts')]):
-            # /home/docs/checkouts/readthedocs.org/user_builds/pytorch_lightning/checkouts/
-            #  devel/pytorch_lightning/utilities/cls_experiment.py#L26-L176
-            path_top = os.path.abspath(os.path.join('..', '..', '..'))
-            fname = os.path.relpath(fname, start=path_top)
-        else:
-            # Local build, imitate master
-            fname = 'master/' + os.path.relpath(fname, start=os.path.abspath('..'))
-        source, lineno = inspect.getsourcelines(obj)
-        return fname, lineno, lineno + len(source) - 1
-
-    if domain != 'py' or not info['module']:
-        return None
-    try:
-        filename = '%s#L%d-L%d' % find_source()
-    except Exception:
-        filename = info['module'].replace('.', '/') + '.py'
-    # import subprocess
-    # tag = subprocess.Popen(['git', 'rev-parse', 'HEAD'], stdout=subprocess.PIPE,
-    #                        universal_newlines=True).communicate()[0][:-1]
-    branch = filename.split('/')[0]
-    # do mapping from latest tags to master
-    branch = {'latest': 'master', 'stable': 'master'}.get(branch, branch)
-    filename = '/'.join([branch] + filename.split('/')[1:])
-    return "https://github.com/%s/%s/blob/%s" \
-           % (github_user, github_repo, filename)
-
-
 autosummary_generate = True
+
 autodoc_member_order = 'groupwise'
+
 autoclass_content = 'both'
-# the options are fixed and will be soon in release,
-#  see https://github.com/sphinx-doc/sphinx/issues/5459
+
 autodoc_default_options = {
     'members': True,
     'methods': True,


Test patch: