docs: Use linkcode to point to source code from docs

Author: tuxuser

.readthedocs.yml

@@ -0,0 +1,21 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings
+
+version: 2
+
+sphinx:
+  # The config file overrides the UI settings:
+  # https://github.com/pyca/cryptography/issues/5863#issuecomment-817828152
+  builder: dirhtml
+
+build:
+  # readdocs master now includes a rust toolchain
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/_ext/linkcode_res.py

@@ -0,0 +1,107 @@
+import importlib
+import inspect
+import os
+import sys
+
+import xbox.webapi
+
+# -- 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(xbox.webapi.__file__))
+
+    if lineno:
+        linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1)
+    else:
+        linespec = ""
+
+    url = "https://github.com/OpenXbox/xbox-webapi-python/blob/%s/xbox/webapi/%s%s"
+    # url = "https://github.com/pyca/cryptography/blob/%s/src/cryptography/%s%s"
+    if "dev" in xbox.webapi.__version__:
+        return url % ("master", fn, linespec)
+    else:
+        version = f"v{xbox.webapi.__version__}"
+        return url % (version, fn, linespec)

docs/conf.py

@@ -18,6 +18,7 @@
 import sys
 
 sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('_ext'))
 
 # -- Project information -----------------------------------------------------
 
@@ -44,9 +45,13 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
-    'recommonmark'
+    'sphinx.ext.linkcode',
+    'sphinx_mdinclude'
 ]
 
+# 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']
 
@@ -166,7 +171,7 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3': None}
 
 # -- Options for napoleon extension ------------------------------------------
 napoleon_google_docstring = True

setup.py

@@ -48,15 +48,19 @@
             "flake8",
             "tox",
             "coverage",
-            "Sphinx",
-            "sphinx_rtd_theme",
-            "recommonmark",
+            # PyPi
             "twine",
+            # Tests
             "pytest",
             "pytest-cov",
             "pytest-asyncio",
             "pytest-runner",
         ],
+        "docs": [
+            "Sphinx",
+            "sphinx_rtd_theme",
+            "sphinx-mdinclude",
+        ],
     },
     entry_points={
         "console_scripts": [