From f89dc2382a374368189a25b8a299fc98fe339a2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Wed, 24 Sep 2025 17:39:54 +0000 Subject: [PATCH 1/7] docs: switch API reference docs to pydata theme --- README.rst | 2 ++ docs/conf.py | 40 ++++++++++++++++++++------------- noxfile.py | 35 +++++++---------------------- scripts/publish_api_coverage.py | 3 +++ 4 files changed, 38 insertions(+), 42 deletions(-) diff --git a/README.rst b/README.rst index 36d3c2ca20..84de370652 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,5 @@ +:orphan: + BigQuery DataFrames (BigFrames) =============================== diff --git a/docs/conf.py b/docs/conf.py index 23ec7a6b36..9d9e9ebd79 100644 --- a/docs/conf.py +++ b/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", diff --git a/noxfile.py b/noxfile.py index 8334fcb0e1..b02952f9c2 100644 --- a/noxfile.py +++ b/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", diff --git a/scripts/publish_api_coverage.py b/scripts/publish_api_coverage.py index 43f7df4dd6..1c052504d3 100644 --- a/scripts/publish_api_coverage.py +++ b/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", From 5b5276b81fb3998e7241401b6cbfc56e172e4831 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Thu, 6 Nov 2025 21:50:29 +0000 Subject: [PATCH 2/7] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20po?= =?UTF-8?q?st-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- docs/conf.py | 40 +++++++++++++++------------------------- 1 file changed, 15 insertions(+), 25 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9d9e9ebd79..23ec7a6b36 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,11 +24,9 @@ # 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 @@ -58,7 +56,7 @@ "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode", - "myst_parser", + "recommonmark", ] # autodoc/autosummary flags @@ -100,7 +98,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 = "en-US" +language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -150,27 +148,19 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "pydata_sphinx_theme" +html_theme = "alabaster" # 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 = { - "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", - }, - ], + "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", } # Add any paths that contain custom themes here, relative to this directory. @@ -274,7 +264,7 @@ # -- Options for LaTeX output --------------------------------------------- -latex_elements: dict[str, Any] = { +latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). @@ -292,7 +282,7 @@ ( root_doc, "bigframes.tex", - "BigQuery DataFrames (BigFrames)", + "bigframes Documentation", author, "manual", ) @@ -327,7 +317,7 @@ ( root_doc, "bigframes", - "BigQuery DataFrames (BigFrames)", + "bigframes Documentation", [author], 1, ) @@ -346,7 +336,7 @@ ( root_doc, "bigframes", - "BigQuery DataFrames (BigFrames)", + "bigframes Documentation", author, "bigframes", "bigframes Library", From 029729e198499d41d4aea20ceb81f07d3f836f28 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Thu, 6 Nov 2025 21:51:16 +0000 Subject: [PATCH 3/7] use python 3.13 to render the docs --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2833fe98ff..fab2463145 100644 --- a/.github/workflows/docs.yml +++ b/.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 From 97ead83d1bf9e33f9631f5b8eb464279a8851a75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Thu, 6 Nov 2025 22:18:40 +0000 Subject: [PATCH 4/7] deploy to github pages --- .github/workflows/docs-deploy.yml | 57 +++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/docs-deploy.yml diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000000..13d4d87263 --- /dev/null +++ b/.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 From 5a87825594e5211ce72f45673a0307612c14bb3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Thu, 6 Nov 2025 22:19:28 +0000 Subject: [PATCH 5/7] =?UTF-8?q?Revert=20"=F0=9F=A6=89=20Updates=20from=20O?= =?UTF-8?q?wlBot=20post-processor"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit 5b5276b81fb3998e7241401b6cbfc56e172e4831. --- docs/conf.py | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 23ec7a6b36..9d9e9ebd79 100644 --- a/docs/conf.py +++ b/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", From 4c6e6d7c98dafb121c549af5a6a78e5d1119616a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Thu, 6 Nov 2025 22:20:26 +0000 Subject: [PATCH 6/7] exclude conf.py from owlbot --- owlbot.py | 1 + 1 file changed, 1 insertion(+) diff --git a/owlbot.py b/owlbot.py index b9145d4367..6058f5d9cd 100644 --- a/owlbot.py +++ b/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", From abfa48a6e94cc18889282ce3ff981033ef064f11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20Swe=C3=B1a?= Date: Thu, 6 Nov 2025 22:25:05 +0000 Subject: [PATCH 7/7] remove unneeded replacement --- owlbot.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/owlbot.py b/owlbot.py index 6058f5d9cd..33dd33a84f 100644 --- a/owlbot.py +++ b/owlbot.py @@ -115,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"],