docs: switch API reference docs to pydata theme (#2237)

* docs: switch API reference docs to pydata theme

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* use python 3.13 to render the docs

* deploy to github pages

* Revert "🦉 Updates from OwlBot post-processor"

This reverts commit 5b5276b.

* exclude conf.py from owlbot

* remove unneeded replacement

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: tswast

.github/workflows/docs-deploy.yml

@@ -0,0 +1,57 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  # TODO(tswast): Update this to only be releases once we confirm it's working.
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+    - name: Install nox
+      run: |
+        python -m pip install --upgrade setuptools pip wheel
+        python -m pip install nox
+    - name: Run docs
+      run: |
+        nox -s docs
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: docs/_build/html/
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs.yml

@@ -12,7 +12,7 @@ jobs:
     - name: Setup Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.13"
     - name: Install nox
       run: |
         python -m pip install --upgrade setuptools pip wheel

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",

owlbot.py

@@ -44,6 +44,7 @@
     excludes=[
         # Need a combined LICENSE for all vendored packages.
         "LICENSE",
+        "docs/conf.py",
         # Multi-processing note isn't relevant, as bigframes is responsible for
         # creating clients, not the end user.
         "docs/multiprocessing.rst",
@@ -114,13 +115,6 @@
     "recursive-include bigframes *.json *.proto *.js *.css py.typed",
 )
 
-# Fixup the documentation.
-assert 1 == s.replace(  # docs/conf.py
-    ["docs/conf.py"],
-    re.escape("Google Cloud Client Libraries for bigframes"),
-    "BigQuery DataFrames provides DataFrame APIs on the BigQuery engine",
-)
-
 # Don't omit `*/core/*.py` when counting test coverages
 assert 1 == s.replace(  # .coveragerc
     [".coveragerc"],

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",