docs: switch API reference docs to pydata theme

Author: tswast

README.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 BigQuery DataFrames (BigFrames)
 ===============================
 

docs/conf.py

@@ -24,9 +24,11 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+from __future__ import annotations
+
 import os
-import shlex
 import sys
+from typing import Any
 
 # 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
@@ -56,7 +58,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
-    "recommonmark",
+    "myst_parser",
 ]
 
 # autodoc/autosummary flags
@@ -98,7 +100,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en-US"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -148,19 +150,27 @@
 
 # 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"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
+# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#references
 html_theme_options = {
-    "description": "BigQuery DataFrames provides DataFrame APIs on the BigQuery engine",
-    "github_user": "googleapis",
-    "github_repo": "python-bigquery-dataframes",
-    "github_banner": True,
-    "font_family": "'Roboto', Georgia, sans",
-    "head_font_family": "'Roboto', Georgia, serif",
-    "code_font_family": "'Roboto Mono', 'Consolas', monospace",
+    "github_url": "https://github.com/googleapis/python-bigquery-dataframes",
+    "logo": {
+        "text": "BigQuery DataFrames (BigFrames)",
+    },
+    "external_links": [
+        {
+            "name": "Getting started",
+            "url": "https://docs.cloud.google.com/bigquery/docs/dataframes-quickstart",
+        },
+        {
+            "name": "User guide",
+            "url": "https://docs.cloud.google.com/bigquery/docs/bigquery-dataframes-introduction",
+        },
+    ],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -264,7 +274,7 @@
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+latex_elements: dict[str, Any] = {
     # The paper size ('letterpaper' or 'a4paper').
     #'papersize': 'letterpaper',
     # The font size ('10pt', '11pt' or '12pt').
@@ -282,7 +292,7 @@
     (
         root_doc,
         "bigframes.tex",
-        "bigframes Documentation",
+        "BigQuery DataFrames (BigFrames)",
         author,
         "manual",
     )
@@ -317,7 +327,7 @@
     (
         root_doc,
         "bigframes",
-        "bigframes Documentation",
+        "BigQuery DataFrames (BigFrames)",
         [author],
         1,
     )
@@ -336,7 +346,7 @@
     (
         root_doc,
         "bigframes",
-        "bigframes Documentation",
+        "BigQuery DataFrames (BigFrames)",
         author,
         "bigframes",
         "bigframes Library",

noxfile.py

@@ -515,24 +515,14 @@ def cover(session):
     session.run("coverage", "erase")
 
 
-@nox.session(python=DEFAULT_PYTHON_VERSION)
+@nox.session(python="3.13")
 def docs(session):
     """Build the docs for this library."""
     session.install("-e", ".[scikit-learn]")
     session.install(
-        # We need to pin to specific versions of the `sphinxcontrib-*` packages
-        # which still support sphinx 4.x.
-        # See https://github.com/googleapis/sphinx-docfx-yaml/issues/344
-        # and https://github.com/googleapis/sphinx-docfx-yaml/issues/345.
-        "sphinxcontrib-applehelp==1.0.4",
-        "sphinxcontrib-devhelp==1.0.2",
-        "sphinxcontrib-htmlhelp==2.0.1",
-        "sphinxcontrib-qthelp==1.0.3",
-        "sphinxcontrib-serializinghtml==1.1.5",
-        SPHINX_VERSION,
-        "alabaster",
-        "recommonmark",
-        "anywidget",
+        "sphinx==8.2.3",
+        "myst-parser==4.0.1",
+        "pydata-sphinx-theme==0.16.1",
     )
 
     shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
@@ -562,19 +552,10 @@ def docfx(session):
 
     session.install("-e", ".[scikit-learn]")
     session.install(
-        # We need to pin to specific versions of the `sphinxcontrib-*` packages
-        # which still support sphinx 4.x.
-        # See https://github.com/googleapis/sphinx-docfx-yaml/issues/344
-        # and https://github.com/googleapis/sphinx-docfx-yaml/issues/345.
-        "sphinxcontrib-applehelp==1.0.4",
-        "sphinxcontrib-devhelp==1.0.2",
-        "sphinxcontrib-htmlhelp==2.0.1",
-        "sphinxcontrib-qthelp==1.0.3",
-        "sphinxcontrib-serializinghtml==1.1.5",
         SPHINX_VERSION,
-        "alabaster",
-        "recommonmark",
-        "gcp-sphinx-docfx-yaml==3.0.1",
+        "pydata-sphinx-theme==0.13.3",
+        "myst-parser==0.18.1",
+        "gcp-sphinx-docfx-yaml==3.2.4",
         "anywidget",
     )
 
@@ -599,7 +580,7 @@ def docfx(session):
             "sphinx.ext.napoleon,"
             "sphinx.ext.todo,"
             "sphinx.ext.viewcode,"
-            "recommonmark"
+            "myst_parser"
         ),
         "-b",
         "html",

scripts/publish_api_coverage.py

@@ -205,6 +205,9 @@ def generate_pandas_api_coverage():
 def generate_sklearn_api_coverage():
     """Explore all SKLearn modules, and for each item contained generate a
     regex to detect it being imported, and record whether we implement it"""
+
+    import sklearn  # noqa
+
     sklearn_modules = [
         "sklearn",
         "sklearn.model_selection",