Fix links to source code in documentation pages (#1444)

Update the `linkcode_resolve` function in Sphinx configuration file so
the links to the source code of each function, class or method points to
the actual code corresponding to that version, and not always to the
code in `main`. Update some Azure configurations: checkout simpeg repo
without shallow depth and fetching tags. Clean up the working directory
before installing SimPEG so the version doesn't have an extra hash.

---------

Co-authored-by: Joseph Capriotti <josephrcapriotti@gmail.com>

.azure-pipelines/matrix.yml

@@ -23,6 +23,15 @@ jobs:
             vmImage: ${{ os }}
           timeoutInMinutes: 120
           steps:
+
+          # Checkout simpeg repo, including tags.
+          # We need to sync tags and disable shallow depth in order to get the
+          # SimPEG version while building the docs.
+          - checkout: self
+            fetchDepth: 0
+            fetchTags: true
+            displayName: Checkout repository (including tags)
+
           - script: |
               wget -O Mambaforge.sh  "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh"
               bash Mambaforge.sh -b -p "${HOME}/conda"
@@ -31,10 +40,14 @@ jobs:
           - script: |
               source "${HOME}/conda/etc/profile.d/conda.sh"
               source "${HOME}/conda/etc/profile.d/mamba.sh"
-              echo "  - python="${{ py_vers }} >> environment_test.yml
-              mamba env create -f environment_test.yml
+              cp environment_test.yml environment_test_with_pyversion.yml
+              echo "  - python="${{ py_vers }} >> environment_test_with_pyversion.yml
+              mamba env create -f environment_test_with_pyversion.yml
+              rm environment_test_with_pyversion.yml
               conda activate simpeg-test
               pip install pytest-azurepipelines
+              echo "\nList installed packages"
+              conda list
             displayName: Create Anaconda testing environment
 
           - script: |
@@ -43,6 +56,12 @@ jobs:
               pip install -e .
             displayName: Build package
 
+          - script: |
+              source "${HOME}/conda/etc/profile.d/conda.sh"
+              conda activate simpeg-test
+              python -c "import simpeg; print(simpeg.__version__)"
+            displayName: Check SimPEG version
+
           - script: |
               source "${HOME}/conda/etc/profile.d/conda.sh"
               conda activate simpeg-test

azure-pipelines.yml

@@ -117,6 +117,8 @@ stages:
             rm environment_test_with_pyversion.yml
             conda activate simpeg-test
             pip install pytest-azurepipelines
+            echo "\nList installed packages"
+            conda list
           displayName: Create Anaconda testing environment
 
         - script: |
@@ -212,6 +214,8 @@ stages:
             rm environment_test_with_pyversion.yml
             conda activate simpeg-test
             pip install pytest-azurepipelines
+            echo "\nList installed packages"
+            conda list
           displayName: Create Anaconda testing environment
 
         - bash: |
@@ -328,6 +332,8 @@ stages:
             rm environment_test_with_pyversion.yml
             conda activate simpeg-test
             pip install pytest-azurepipelines
+            echo "\nList installed packages"
+            conda list
           displayName: Create Anaconda testing environment
 
         - bash: |
@@ -384,4 +390,4 @@ stages:
             echo -e "\nFinished uploading generated files."
           displayName: Push documentation to simpeg-doctest
           env:
-            GH_TOKEN: $(gh.token)
+            GH_TOKEN: $(gh.token)

docs/conf.py

@@ -48,7 +48,6 @@
     "sphinx.ext.mathjax",
     "sphinx_gallery.gen_gallery",
     "sphinx.ext.todo",
-    "sphinx.ext.linkcode",
     "matplotlib.sphinxext.plot_directive",
 ]
 
@@ -136,17 +135,24 @@
 # edit_on_github_branch = "main/docs"
 # check_meta = False
 
-# source code links
+
+# -----------------
+# Source code links
+# -----------------
+# Function inspired in matplotlib's configuration
+
 link_github = True
-# You can build old with link_github = False
 
 if link_github:
     import inspect
-    from os.path import relpath, dirname
+    from packaging.version import parse
 
     extensions.append("sphinx.ext.linkcode")
 
     def linkcode_resolve(domain, info):
+        """
+        Determine the URL corresponding to Python object
+        """
         if domain != "py":
             return None
 
@@ -161,44 +167,45 @@ def linkcode_resolve(domain, info):
         for part in fullname.split("."):
             try:
                 obj = getattr(obj, part)
-            except Exception:
+            except AttributeError:
                 return None
 
-        try:
-            unwrap = inspect.unwrap
-        except AttributeError:
-            pass
-        else:
-            obj = unwrap(obj)
-
+        if inspect.isfunction(obj):
+            obj = inspect.unwrap(obj)
         try:
             fn = inspect.getsourcefile(obj)
-        except Exception:
+        except TypeError:
             fn = None
+        if not fn or fn.endswith("__init__.py"):
+            try:
+                fn = inspect.getsourcefile(sys.modules[obj.__module__])
+            except (TypeError, AttributeError, KeyError):
+                fn = None
         if not fn:
             return None
 
         try:
             source, lineno = inspect.getsourcelines(obj)
-        except Exception:
+        except (OSError, TypeError):
             lineno = None
 
         if lineno:
-            linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+            linespec = f"#L{lineno:d}-L{lineno + len(source) - 1:d}"
         else:
             linespec = ""
 
         try:
-            fn = relpath(fn, start=dirname(simpeg.__file__))
+            fn = os.path.relpath(fn, start=os.path.dirname(simpeg.__file__))
         except ValueError:
             return None
 
-        return f"https://github.com/simpeg/simpeg/blob/main/simpeg/{fn}{linespec}"
+        simpeg_version = parse(simpeg.__version__)
+        tag = "main" if simpeg_version.is_devrelease else f"v{simpeg_version.public}"
+        return f"https://github.com/simpeg/simpeg/blob/{tag}/simpeg/{fn}{linespec}"
 
 else:
     extensions.append("sphinx.ext.viewcode")
 
-
 # Make numpydoc to generate plots for example sections
 numpydoc_use_plots = True
 plot_pre_code = """