build: update docs build

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:

docs/conf.py

@@ -86,7 +86,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_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

noxfile.py

@@ -644,7 +644,9 @@ def snippetgen(session):
 
 @nox.session(python="3.10")
 def docs(session):
-    """Build the docs."""
+    """Build the docs for this library."""
+
+    session.install("-e", ".")
 
     session.install(
         # We need to pin to specific versions of the `sphinxcontrib-*` packages
@@ -657,21 +659,68 @@ def docs(session):
         "sphinxcontrib-qthelp==1.0.3",
         "sphinxcontrib-serializinghtml==1.1.5",
         "sphinx==4.5.0",
-        "sphinx_rtd_theme",
+        "alabaster",
+        "recommonmark",
     )
-    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",
+        "-W",  # warnings as errors
+        "-T",  # show full traceback on exception
+        "-N",  # no colors
+        "-b",
+        "html",
+        "-d",
+        os.path.join("docs", "_build", "doctrees", ""),
+        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",
+        "alabaster",
+        "recommonmark",
+    )
+
+    shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
+    session.run(
+        "sphinx-build",
+        "-T",  # show full traceback on exception
+        "-N",  # no colors
+        "-D",
+        (
+            "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",
         "-d",
-        "docs/_build/doctrees",
-        "docs/",
-        "docs/_build/html/",
+        os.path.join("docs", "_build", "doctrees", ""),
+        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