build: update docs build (#2339)

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

Author: parthea

.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:

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

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

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

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

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

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

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

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

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