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 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 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/owlbot.py b/owlbot.py index b9145d4367..33dd33a84f 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", @@ -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"], 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",