docs[python]: Update Sphinx config (#4749)

py-polars/docs/requirements-docs.txt

@@ -1,7 +1,7 @@
 hypothesis==6.54.5
 
 ghp-import==2.1.0
-sphinx==4.3.2
+sphinx==5.1.1
 pydata-sphinx-theme==0.10.1
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2

py-polars/docs/source/conf.py

@@ -9,9 +9,11 @@
 # 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.
-#
+
+import inspect
 import os
 import sys
+import warnings
 
 # add polars directory
 sys.path.insert(0, os.path.abspath("../.."))
@@ -32,13 +34,14 @@
     "numpydoc",  # numpy docstrings
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
-    "sphinx.ext.todo",
+    "sphinx.ext.ifconfig",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.coverage",
+    "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
-    "sphinx.ext.ifconfig",
+    "sphinx.ext.todo",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -54,8 +57,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-# html_theme = 'alabaster'
+
 html_theme = "pydata_sphinx_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -64,6 +66,8 @@
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]  # relative to html_static_path
 
+html_show_sourcelink = False
+
 html_logo = "../img/polars_logo.png"
 autosummary_generate = True
 
@@ -95,3 +99,65 @@
         },
     ],
 }
+
+
+def linkcode_resolve(domain, info):
+    """
+    Determine the URL corresponding to Python object.
+
+    Based on pandas equivalent:
+    https://github.com/pandas-dev/pandas/blob/main/doc/source/conf.py#L629-L686
+    """
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            with warnings.catch_warnings():
+                # Accessing deprecated objects will generate noisy warnings
+                warnings.simplefilter("ignore", FutureWarning)
+                obj = getattr(obj, part)
+        except AttributeError:
+            return None
+
+    try:
+        fn = inspect.getsourcefile(inspect.unwrap(obj))
+    except TypeError:
+        try:  # property
+            fn = inspect.getsourcefile(inspect.unwrap(obj.fget))
+        except (AttributeError, TypeError):
+            fn = None
+    if not fn:
+        return None
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except TypeError:
+        try:  # property
+            source, lineno = inspect.getsourcelines(obj.fget)
+        except (AttributeError, TypeError):
+            lineno = None
+    except OSError:
+        lineno = None
+
+    if lineno:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    conf_dir_path = os.path.dirname(os.path.realpath(__file__))
+    polars_root = os.path.abspath(f"{conf_dir_path}/../../polars")
+
+    fn = os.path.relpath(fn, start=polars_root)
+
+    return (
+        f"https://github.com/pola-rs/polars/blob/master/py-polars/polars/{fn}{linespec}"
+    )

py-polars/tests/docs/run_doc_examples.py

@@ -55,7 +55,7 @@ def modules_in_path(p: Path) -> Iterator[ModuleType]:
     # Will still report errors if the code is invalid
     IGNORE_RESULT_ALL = False
 
-    # Below the implementation if the IGNORE_RESULT directive
+    # Below the implementation of the IGNORE_RESULT directive
     # You can ignore the result of a doctest by adding "doctest: +IGNORE_RESULT" into
     # the code block. The difference with SKIP is that if the code errors on running,
     # that will still be reported.