build: update docs build (#2339)

parthea · gcf-owl-bot[bot] · web-flow · commit ab4cc4aefc79 · 2025-05-09T15:18:23.000Z
Co-authored-by: Owl Bot &lt;gcf-owl-bot[bot]@users.noreply.github.com&gt;
diff --git a/packages/gapic-generator/.github/workflows/tests.yaml b/packages/gapic-generator/.github/workflows/tests.yaml
@@ -33,6 +33,21 @@ jobs:
         run: python -m pip install nox
       - name: Build the documentation.
         run: nox -s docs
+  docfx:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        # Use python 3.10 for docs to match the version for the sphinx plugin
+        # https://github.com/googleapis/synthtool/pull/1891
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install nox.
+        run: python -m pip install nox
+      - name: Build the documentation.
+        run: nox -s docfx
   mypy:
     strategy:
       matrix:
diff --git a/packages/gapic-generator/gapic/templates/noxfile.py.j2 b/packages/gapic-generator/gapic/templates/noxfile.py.j2
@@ -370,10 +370,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/noxfile.py b/packages/gapic-generator/noxfile.py
@@ -630,7 +630,9 @@ def snippetgen(session):
 
 @nox.session(python="3.10")
 def docs(session):
-    """Build the docs."""
+    """Build the docs for this generator."""
+
+    session.install("-e", ".")
 
     session.install(
         # We need to pin to specific versions of the `sphinxcontrib-*` packages
@@ -643,21 +645,68 @@ def docs(session):
         "sphinxcontrib-qthelp==1.0.3",
         "sphinxcontrib-serializinghtml==1.1.5",
         "sphinx==4.5.0",
-        "sphinx_rtd_theme",
+        "sphinx-rtd-theme",
+    )
+
+    shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
+    session.run(
+        "sphinx-build",
+        "-W",  # warnings as errors
+        "-T",  # show full traceback on exception
+        "-N",  # no colors
+        "-b",
+        "html",  # builder
+        "-d",
+        os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
+        os.path.join("docs", ""),
+        os.path.join("docs", "_build", "html", ""),
+    )
+
+
+@nox.session(python="3.10")
+def docfx(session):
+    """Build the docfx yaml files for this library."""
+
+    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",
+        "sphinx-rtd-theme",
     )
-    session.install(".")
 
-    # Build the docs!
-    session.run("rm", "-rf", "docs/_build/")
+    shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
     session.run(
         "sphinx-build",
-        "-W",
+        "-T",  # show full traceback on exception
+        "-N",  # no colors
+        "-D",  # Override configuration values set in the conf.py file
+        (
+            "extensions=sphinx.ext.autodoc,"
+            "sphinx.ext.autosummary,"
+            "docfx_yaml.extension,"
+            "sphinx.ext.intersphinx,"
+            "sphinx.ext.coverage,"
+            "sphinx.ext.napoleon,"
+            "sphinx.ext.todo,"
+            "sphinx.ext.viewcode,"
+            "recommonmark"
+        ),
         "-b",
-        "html",
+        "html",  # builder
         "-d",
-        "docs/_build/doctrees",
-        "docs/",
-        "docs/_build/html/",
+        os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
+        os.path.join("docs", ""),
+        os.path.join("docs", "_build", "html", ""),
     )
 
 
diff --git a/packages/gapic-generator/owlbot.py b/packages/gapic-generator/owlbot.py
@@ -18,7 +18,7 @@
 templated_files = CommonTemplates().py_library()
 s.move(
     templated_files / ".kokoro",
-    excludes=["samples/**/*", "test-samples*", "publish-docs.sh", "*/prerelease-deps.cfg"],
+    excludes=["samples/**/*", "test-samples*", "*/prerelease-deps.cfg"],
 )
 
 # needed for docs build
diff --git a/packages/gapic-generator/tests/integration/goldens/asset/noxfile.py b/packages/gapic-generator/tests/integration/goldens/asset/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/credentials/noxfile.py b/packages/gapic-generator/tests/integration/goldens/credentials/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/eventarc/noxfile.py b/packages/gapic-generator/tests/integration/goldens/eventarc/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/logging/noxfile.py b/packages/gapic-generator/tests/integration/goldens/logging/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/logging_internal/noxfile.py b/packages/gapic-generator/tests/integration/goldens/logging_internal/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/redis/noxfile.py b/packages/gapic-generator/tests/integration/goldens/redis/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )
diff --git a/packages/gapic-generator/tests/integration/goldens/redis_selective/noxfile.py b/packages/gapic-generator/tests/integration/goldens/redis_selective/noxfile.py
@@ -364,10 +364,9 @@ def docs(session):
         "-W",  # warnings as errors
         "-T",  # show full traceback on exception
         "-N",  # no colors
-        "-b",
-        "html",
-        "-d",
-        os.path.join("docs", "_build", "doctrees", ""),
+        "-b",  "html",  # builder
+        "-d",  os.path.join("docs", "_build", "doctrees", ""),  # cache directory
+        # paths to build:
         os.path.join("docs", ""),
         os.path.join("docs", "_build", "html", ""),
     )

Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@`
`18`	`18`	`templated_files = CommonTemplates().py_library()`
`19`	`19`	`s.move(`
`20`	`20`	`templated_files / ".kokoro",`
`21`		`- excludes=["samples/*/", "test-samples", "publish-docs.sh", "/prerelease-deps.cfg"],`
	`21`	`+ excludes=["samples/*/", "test-samples", "/prerelease-deps.cfg"],`
`22`	`22`	`)`
`23`	`23`
`24`	`24`	`# needed for docs build`