docs(bigquery): fix table rendering in markdown docs

packages/google-cloud-bigquery/docs/conf.py

@@ -24,9 +24,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 import shlex
+import sys
 
 # 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
@@ -37,6 +37,26 @@
 # See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85
 sys.path.insert(0, os.path.abspath("."))
 
+# sphinx-markdown-builder unconditionally inserts trailing newlines into
+# table cell paragraphs, breaking DevSite table formatting. Suppressing
+# newlines while inside table cells preserves valid GFM tables.
+try:
+    import sphinx_markdown_builder.markdown_writer as _smb_writer
+
+    _orig_depart_paragraph = _smb_writer.MarkdownTranslator.depart_paragraph
+
+    def _table_safe_depart_paragraph(self, node):
+        if getattr(self, "table_entries", None):
+            return
+        return _orig_depart_paragraph(self, node)
+
+    _smb_writer.MarkdownTranslator.depart_paragraph = _table_safe_depart_paragraph
+    _smb_writer.MarkdownTranslator.depart_compact_paragraph = (
+        _table_safe_depart_paragraph
+    )
+except ImportError:
+    pass
+
 __version__ = ""
 
 # -- General configuration ------------------------------------------------

packages/google-cloud-bigquery/tests/unit/test_docs.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pathlib
+import runpy
+
+
+def test_docs_conf_executes_successfully():
+    docs_dir = pathlib.Path(__file__).parent.parent.parent / "docs"
+    conf_path = docs_dir / "conf.py"
+
+    if not conf_path.exists():
+        import pytest
+
+        pytest.skip("docs/conf.py not found")
+
+    res = runpy.run_path(str(conf_path))
+
+    assert "project" in res
+    assert res["project"] == "google-cloud-bigquery"