Replace broken viewcode with linkcode in doc (#6207)

2 files changed, 168 insertions, 0 deletions

diff --git a/docs/_ext/cryptography-docs.py b/docs/_ext/cryptography-docs.py
new file mode 100644
index 000000000..1131f6a0e
--- /dev/null
+++ b/docs/_ext/cryptography-docs.py
@@ -0,0 +1,62 @@
+# This file is dual licensed under the terms of the Apache License, Version
+# 2.0, and the BSD License. See the LICENSE file in the root of this repository
+# for complete details.
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+DANGER_MESSAGE = """
+This is a "Hazardous Materials" module. You should **ONLY** use it if you're
+100% absolutely sure that you know what you're doing because this module is
+full of land mines, dragons, and dinosaurs with laser guns.
+"""
+
+DANGER_ALTERNATE = """
+
+You may instead be interested in :doc:`{alternate}`.
+"""
+
+
+class HazmatDirective(Directive):
+    has_content = True
+
+    def run(self):
+        message = DANGER_MESSAGE
+        if self.content:
+            message += DANGER_ALTERNATE.format(alternate=self.content[0])
+
+        content = nodes.paragraph("", message)
+        admonition_node = Hazmat("\n".join(content))
+        self.state.nested_parse(content, self.content_offset, admonition_node)
+        admonition_node.line = self.lineno
+        return [admonition_node]
+
+
+class Hazmat(nodes.Admonition, nodes.Element):
+    pass
+
+
+def html_visit_hazmat_node(self, node):
+    return self.visit_admonition(node, "danger")
+
+
+def latex_visit_hazmat_node(self, node):
+    return self.visit_admonition(node)
+
+
+def depart_hazmat_node(self, node):
+    return self.depart_admonition(node)
+
+
+def setup(app):
+    app.add_node(
+        Hazmat,
+        html=(html_visit_hazmat_node, depart_hazmat_node),
+        latex=(latex_visit_hazmat_node, depart_hazmat_node),
+    )
+    app.add_directive("hazmat", HazmatDirective)
+
+    return {
+        "parallel_read_safe": True,
+    }
diff --git a/docs/_ext/linkcode_res.py b/docs/_ext/linkcode_res.py
new file mode 100644
index 000000000..9b6f427d4
--- /dev/null
+++ b/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)