docs: improve readability of API method signatures (#2460)

Co-authored-by: Håkon V. Treider <haakonvt@gmail.com>

Author: MortGron

docs/source/_static/css/custom.css

@@ -0,0 +1,21 @@
+/* Source: https://github.com/readthedocs/sphinx_rtd_theme/issues/1529#issuecomment-1918561608*/
+
+/* Take out pointless vertical whitespace in the signatures. */
+.rst-content dl .sig dl,
+.rst-content dl .sig dd {
+  margin-bottom: 0;
+}
+
+/* Make signature boxes full-width, with view-source and header links right-aligned. */
+.rst-content dl .sig {
+  width: -webkit-fill-available;
+}
+.rst-content .viewcode-link {
+  display: inline-flex;
+  float: inline-end;
+  margin-right: 1.5em;
+}
+.rst-content .headerlink {
+  position: absolute;
+  right: 0.5em;
+}

docs/source/conf.py

@@ -23,7 +23,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = "7.2"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -93,7 +93,8 @@
 # Add any paths that contain custom _static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin _static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -159,3 +160,22 @@
         "Miscellaneous",
     )
 ]
+
+python_maximum_signature_line_length = 80
+
+# Patch Sphinx to hide @overload signatures in docs
+# Sphinx's autodoc uses ModuleAnalyzer.overloads via the parser
+# We patch the analyze method to clear overloads after parsing
+# To see why, check out https://github.com/cognitedata/cognite-sdk-python/pull/2460
+from sphinx.pycode import ModuleAnalyzer  # noqa: E402
+
+analyze_fn = ModuleAnalyzer.analyze
+
+
+def analyze_but_skip_overloads(self):
+    result = analyze_fn(self)
+    self.overloads = {}  # Clear overloads after analysis
+    return result
+
+
+ModuleAnalyzer.analyze = analyze_but_skip_overloads