Replace broken viewcode with linkcode in doc (#6207)

.readthedocs.yml

@@ -1,3 +1,5 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings
+
 version: 2
 
 sphinx:
@@ -10,4 +12,11 @@ build:
   os: "ubuntu-20.04"
   tools:
     python: "3.9"
+    rust: "1.55"
 
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/_ext/linkcode_res.py

@@ -0,0 +1,106 @@
+import importlib
+import inspect
+import os
+import sys
+
+import cryptography
+
+# -- Linkcode resolver -----------------------------------------------------
+
+# This is HEAVILY inspired by numpy's
+# https://github.com/numpy/numpy/blob/73fe877ff967f279d470b81ad447b9f3056c1335/doc/source/conf.py#L390
+
+# Copyright (c) 2005-2020, NumPy Developers.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+#        notice, this list of conditions and the following disclaimer.
+#
+#     * Redistributions in binary form must reproduce the above
+#        copyright notice, this list of conditions and the following
+#        disclaimer in the documentation and/or other materials provided
+#        with the distribution.
+#
+#     * Neither the name of the NumPy Developers nor the names of any
+#        contributors may be used to endorse or promote products derived
+#        from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+def linkcode_resolve(domain, info):
+    """
+    Determine the url corresponding to Python object
+    """
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    try:
+        importlib.import_module(modname)
+    except Exception:
+        return None
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except Exception:
+            return None
+
+    # strip decorators, which would resolve to the source of the decorator
+    # possibly an upstream bug in getsourcefile, bpo-1764286
+    try:
+        unwrap = inspect.unwrap
+    except AttributeError:
+        pass
+    else:
+        obj = unwrap(obj)
+
+    fn = None
+    lineno = None
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:
+        fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:
+        lineno = None
+
+    fn = os.path.relpath(fn, start=os.path.dirname(cryptography.__file__))
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    url = "https://github.com/pyca/cryptography/blob/%s/src/cryptography/%s%s"
+    if "dev" in cryptography.__version__:
+        return url % ("main", fn, linespec)
+    else:
+        version = ".".join(cryptography.__version__.split(".")[:2] + ["x"])
+        return url % (version, fn, linespec)

docs/conf.py

@@ -33,7 +33,7 @@ except ImportError:
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath("_ext"))
 
 # -- General configuration ----------------------------------------------------
 
@@ -47,13 +47,16 @@ extensions = [
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
     "cryptography-docs",
 ]
 
 if spelling is not None:
     extensions.append("sphinxcontrib.spelling")
 
+# Linkcode resolver
+from linkcode_res import linkcode_resolve  # noqa: E402, F401
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]