From 1271b18f14efb2d8c9bb3a5b35db2e949111cec5 Mon Sep 17 00:00:00 2001
From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com>
Date: Tue, 16 Jan 2024 22:26:15 +0000
Subject: [PATCH] build(python): fix `docs` and `docfx` builds (#1779)

Source-Link: https://togithub.com/googleapis/synthtool/commit/fac8444edd5f5526e804c306b766a271772a3e2f
Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:5ea6d0ab82c956b50962f91d94e206d3921537ae5fe1549ec5326381d8905cfa
---
 .github/.OwlBot.lock.yaml |   6 +-
 .kokoro/requirements.txt  |   6 +-
 docs/reference.rst        | 115 ++++----------------------------------
 noxfile.py                |  24 +++++++-
 4 files changed, 39 insertions(+), 112 deletions(-)

diff --git a/.github/.OwlBot.lock.yaml b/.github/.OwlBot.lock.yaml
index 773c1dfd2..d8a1bbca7 100644
--- a/.github/.OwlBot.lock.yaml
+++ b/.github/.OwlBot.lock.yaml
@@ -1,4 +1,4 @@
-# Copyright 2023 Google LLC
+# Copyright 2024 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,5 +13,5 @@
 # limitations under the License.
 docker:
   image: gcr.io/cloud-devrel-public-resources/owlbot-python:latest
-  digest: sha256:2f155882785883336b4468d5218db737bb1d10c9cea7cb62219ad16fe248c03c
-# created: 2023-11-29T14:54:29.548172703Z
+  digest: sha256:5ea6d0ab82c956b50962f91d94e206d3921537ae5fe1549ec5326381d8905cfa
+# created: 2024-01-15T16:32:08.142785673Z
diff --git a/.kokoro/requirements.txt b/.kokoro/requirements.txt
index e5c1ffca9..bb3d6ca38 100644
--- a/.kokoro/requirements.txt
+++ b/.kokoro/requirements.txt
@@ -263,9 +263,9 @@ jeepney==0.8.0 \
     # via
     #   keyring
     #   secretstorage
-jinja2==3.1.2 \
-    --hash=sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852 \
-    --hash=sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61
+jinja2==3.1.3 \
+    --hash=sha256:7d6d50dd97d52cbc355597bd845fabfbac3f551e1f99619e39a35ce8c370b5fa \
+    --hash=sha256:ac8bd6544d4bb2c9792bf3a159e80bba8fda7f07e81bc3aed565432d5925ba90
     # via gcp-releasetool
 keyring==24.2.0 \
     --hash=sha256:4901caaf597bfd3bbd78c9a0c7c4c29fcd8310dab2cffefe749e916b6527acd6 \
diff --git a/docs/reference.rst b/docs/reference.rst
index b886f1161..6c00df077 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -1,8 +1,6 @@
 API Reference
 ~~~~~~~~~~~~~
 
-.. currentmodule:: google.cloud.bigquery
-
 The main concepts with this API are:
 
 - :class:`~google.cloud.bigquery.client.Client` manages connections to the
@@ -18,55 +16,12 @@ The main concepts with this API are:
 Client
 ======
 
-.. autosummary::
-    :toctree: generated
-
-    client.Client
+.. automodule:: google.cloud.bigquery.client
 
 Job
 ===
 
-Job Configuration
------------------
-
-.. autosummary::
-    :toctree: generated
-
-    job.QueryJobConfig
-    job.CopyJobConfig
-    job.LoadJobConfig
-    job.ExtractJobConfig
-
-Job Classes
------------
-
-.. autosummary::
-    :toctree: generated
-
-    job.QueryJob
-    job.CopyJob
-    job.LoadJob
-    job.ExtractJob
-
-Job-Related Types
------------------
-
-.. autosummary::
-    :toctree: generated
-
-    job.Compression
-    job.CreateDisposition
-    job.DestinationFormat
-    job.DmlStats
-    job.Encoding
-    job.OperationType
-    job.QueryPlanEntry
-    job.QueryPlanEntryStep
-    job.QueryPriority
-    job.ReservationUsage
-    job.SourceFormat
-    job.WriteDisposition
-    job.SchemaUpdateOption
+.. automodule:: google.cloud.bigquery.job
 
 .. toctree::
   :maxdepth: 2
@@ -77,63 +32,28 @@ Job-Related Types
 Dataset
 =======
 
-.. autosummary::
-    :toctree: generated
-
-    dataset.Dataset
-    dataset.DatasetListItem
-    dataset.DatasetReference
-    dataset.AccessEntry
+.. automodule:: google.cloud.bigquery.dataset
 
 
 Table
 =====
 
-.. autosummary::
-    :toctree: generated
-
-    table.PartitionRange
-    table.RangePartitioning
-    table.Row
-    table.RowIterator
-    table.SnapshotDefinition
-    table.CloneDefinition
-    table.Table
-    table.TableListItem
-    table.TableReference
-    table.TimePartitioning
-    table.TimePartitioningType
+.. automodule:: google.cloud.bigquery.table
 
 Model
 =====
 
-.. autosummary::
-    :toctree: generated
-
-    model.Model
-    model.ModelReference
+.. automodule:: google.cloud.bigquery.model
 
 Routine
 =======
 
-.. autosummary::
-    :toctree: generated
-
-    routine.DeterminismLevel
-    routine.Routine
-    routine.RoutineArgument
-    routine.RoutineReference
-    routine.RoutineType
+.. automodule:: google.cloud.bigquery.routine
 
 Schema
 ======
 
-.. autosummary::
-    :toctree: generated
-
-    schema.SchemaField
-    schema.PolicyTagList
-
+.. automodule:: google.cloud.bigquery.schema
 
 Query
 =====
@@ -147,25 +67,13 @@ Query
 Retries
 =======
 
-.. autosummary::
-    :toctree: generated
-
-    retry.DEFAULT_RETRY
+.. automodule:: google.cloud.bigquery.retry
 
 
 External Configuration
 ======================
 
-.. autosummary::
-    :toctree: generated
-
-    external_config.ExternalSourceFormat
-    external_config.ExternalConfig
-    external_config.BigtableOptions
-    external_config.BigtableColumnFamily
-    external_config.BigtableColumn
-    external_config.CSVOptions
-    external_config.GoogleSheetsOptions
+.. automodule:: google.cloud.bigquery.external_config
 
 .. toctree::
     :maxdepth: 2
@@ -194,10 +102,7 @@ Enums
 Encryption Configuration
 ========================
 
-.. autosummary::
-    :toctree: generated
-
-    encryption_configuration.EncryptionConfiguration
+.. automodule:: google.cloud.bigquery.encryption_configuration
 
 
 Additional Types
diff --git a/noxfile.py b/noxfile.py
index 66d68c04e..ae022232e 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -418,7 +418,20 @@ def blacken(session):
 def docs(session):
     """Build the docs."""
 
-    session.install("recommonmark", "sphinx==4.0.2", "sphinx_rtd_theme")
+    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==4.5.0",
+        "alabaster",
+        "recommonmark",
+    )
     session.install("google-cloud-storage")
     session.install("-e", ".[all]")
 
@@ -443,6 +456,15 @@ def docfx(session):
 
     session.install("-e", ".")
     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",
         "gcp-sphinx-docfx-yaml",
         "alabaster",
         "recommonmark",