Skip to content

docs(bigquery): fix table rendering in markdown docs - #18294

Merged
shuoweil merged 6 commits into
mainfrom
shuowei-fix-bigquery-docs-table-format
Sep 10, 2026
Merged

docs(bigquery): fix table rendering in markdown docs#18294
shuoweil merged 6 commits into
mainfrom
shuowei-fix-bigquery-docs-table-format

Conversation

@shuoweil

@shuoweil shuoweil commented Sep 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This monkeypatch is an isolated workaround in docs/conf.py while a permanent upstream fix is not scheduled in gcp-sphinx-docfx-yaml.

Fixes table formatting in the generated Markdown reference documentation for google-cloud-bigquery.
When building Markdown documentation via sphinx-markdown-builder, table cell paragraphs unconditionally emit trailing newlines. This breaks single-line GitHub Flavored Markdown (GFM) table rows, causing cell padding to be interpreted as 4-space indented code blocks on reference doc pages.

This change adds a targeted patch in docs/conf.py that suppresses newlines when exiting paragraphs inside table cells, restoring valid GFM table syntax.

before: screen/3oup25c57irb8
after: screen/4GqUXF7gs4p6GZV (render locally with nox -s doxfx)
stage: https://clouddocs.devsite.corp.google.com/python/docs/reference/bigquery/latest

Fixes #<522853190> 🦕

@shuoweil
shuoweil requested review from a team as code owners September 4, 2026 19:26
@shuoweil
shuoweil requested review from Edvc97, sycai and tswast and removed request for a team September 4, 2026 19:26
@shuoweil shuoweil self-assigned this Sep 4, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Sep 4, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a workaround in docs/conf.py to suppress trailing newlines in table cells generated by sphinx-markdown-builder, preserving valid GFM tables. It also adds a unit test to verify that docs/conf.py executes successfully. The reviewer recommended gracefully skipping this new unit test if docs/conf.py is not found, which can happen when tests are run against an installed package where the docs/ directory is absent.

Comment thread packages/google-cloud-bigquery/tests/unit/test_docs.py
shuoweil and others added 2 commits September 4, 2026 12:39
@shuoweil @gemini-code-assist
Update packages/google-cloud-bigquery/tests/unit/test_docs.py
319959b 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@shuoweil
style: format test_docs.py with black
34eb197
sycai
sycai reviewed Sep 9, 2026
View reviewed changes
Comment thread packages/google-cloud-bigquery/tests/unit/test_docs.py

@sycai sycai Sep 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you provide some details on how this test is covering the changes in conf.py ?

@shuoweil shuoweil Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

test_docs.py is currently a smoke test to verify docs/conf.py executes without runtime errors and preserves basic configuration.

Because documentation dependencies (sphinx-markdown-builder) are not installed in the unit test environment, the monkeypatch logic is bypassed during unit tests via except ImportError. The formatting fix itself was verified end-to-end using nox -s docfx by inspecting the generated Markdown (docs/_build/html/docfx_yaml/index.md).

I add unit test for markdown translator monkeypatch.

@shuoweil
shuoweil requested a review from sycai September 9, 2026 22:50
tswast
tswast reviewed Sep 10, 2026
View reviewed changes

@tswast tswast left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "after" screen/4GqUXF7gs4p6GZV is showing the view from Sphinx, but not the rendered view for the "Cloud RAD" docs. Please stage the documents there to evaluate this change properly.

go/cloud-rad/python?polyglot=split-repository#setup-for-staging-local-changes

@shuoweil

shuoweil commented Sep 10, 2026

Copy link
Copy Markdown
Contributor Author

The "after" screen/4GqUXF7gs4p6GZV is showing the view from Sphinx, but not the rendered view for the "Cloud RAD" docs. Please stage the documents there to evaluate this change properly.

go/cloud-rad/python?polyglot=split-repository#setup-for-staging-local-changes

Thanks, Tim. Here is the local stage: https://clouddocs.devsite.corp.google.com/python/docs/reference/bigquery/latest

@shuoweil
shuoweil requested a review from tswast September 10, 2026 18:23
@shuoweil
shuoweil merged commit 1abfcdd into main Sep 10, 2026
47 checks passed
@shuoweil
shuoweil deleted the shuowei-fix-bigquery-docs-table-format branch September 10, 2026 20:14
@release-please release-please Bot mentioned this pull request Sep 10, 2026
Merged
suztomo pushed a commit that referenced this pull request Sep 14, 2026
@release-please
chore: release main (#18293)
ed25a5c 
🤖 I have created a release *beep* *boop*
---


<details><summary>google-ads-admanager: 0.10.4</summary>

##
[0.10.4](google-ads-admanager-v0.10.3...google-ads-admanager-v0.10.4)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-api-core: 2.37.0</summary>

##
[2.37.0](google-api-core-v2.36.0...google-api-core-v2.37.0)
(2026-09-14)


### Features

* **gapic:** add OpenTelemetry T3 client method span wrapping in
gapic_v1.method (D)
([#18274](#18274))
([156e319](156e319))
</details>

<details><summary>google-cloud-alloydb: 0.11.2</summary>

##
[0.11.2](google-cloud-alloydb-v0.11.1...google-cloud-alloydb-v0.11.2)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-bigquery: 3.45.1</summary>

##
[3.45.1](google-cloud-bigquery-v3.45.0...google-cloud-bigquery-v3.45.1)
(2026-09-14)


### Bug Fixes

* bump idna from 3.10 to 3.15 in
/packages/google-cloud-bigquery/samples/geography
([#18309](#18309))
([b6fe689](b6fe689))
* bump pyarrow from 21.0.0 to 23.0.1 in
/packages/google-cloud-bigquery/samples/geography
([#18313](#18313))
([282ab70](282ab70))
* bump pyasn1 from 0.6.2 to 0.6.4 in
/packages/google-cloud-bigquery/samples/geography
([#18310](#18310))
([1d79696](1d79696))
* bump pytest from 8.4.2 to 9.0.3 in
/packages/google-cloud-bigquery/samples/desktopapp
([#18322](#18322))
([f55462d](f55462d))
* bump pytest from 8.4.2 to 9.0.3 in
/packages/google-cloud-bigquery/samples/magics
([#18312](#18312))
([d0045d4](d0045d4))
* bump requests from 2.32.5 to 2.33.0 in
/packages/google-cloud-bigquery/samples/geography
([#18323](#18323))
([4cc95cb](4cc95cb))
* bump urllib3 from 2.6.3 to 2.7.0 in
/packages/google-cloud-bigquery/samples/geography
([#18311](#18311))
([f18eb1e](f18eb1e))


### Documentation

* **bigquery:** fix table rendering in markdown docs
([#18294](#18294))
([1abfcdd](1abfcdd))
* migrate code from googleapis/python-bigquery
([#18303](#18303))
([23f9a74](23f9a74))
</details>

<details><summary>google-cloud-bigtable: 2.45.0</summary>

##
[2.45.0](google-cloud-bigtable-v2.44.0...google-cloud-bigtable-v2.45.0)
(2026-09-14)


### Features

* **bigtable:** Rerouted MutateRows to use the data client
([#18195](#18195))
([3bbcbdf](3bbcbdf))
</details>

<details><summary>google-cloud-chronicle: 0.6.3</summary>

##
[0.6.3](google-cloud-chronicle-v0.6.2...google-cloud-chronicle-v0.6.3)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-compute: 1.53.0</summary>

##
[1.53.0](google-cloud-compute-v1.52.0...google-cloud-compute-v1.53.0)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-compute-v1beta: 0.12.5</summary>

##
[0.12.5](google-cloud-compute-v1beta-v0.12.4...google-cloud-compute-v1beta-v0.12.5)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-geminidataanalytics: 0.13.3</summary>

##
[0.13.3](google-cloud-geminidataanalytics-v0.13.2...google-cloud-geminidataanalytics-v0.13.3)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-retail: 2.13.0</summary>

##
[2.13.0](google-cloud-retail-v2.12.0...google-cloud-retail-v2.13.0)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-vectorsearch: 0.11.3</summary>

##
[0.11.3](google-cloud-vectorsearch-v0.11.2...google-cloud-vectorsearch-v0.11.3)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

<details><summary>google-cloud-visionai: 0.5.2</summary>

##
[0.5.2](google-cloud-visionai-v0.5.1...google-cloud-visionai-v0.5.2)
(2026-09-14)


### Features

* update API sources and regenerate
([#18324](#18324))
([0766fb6](0766fb6))
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sycai sycai sycai approved these changes
@Edvc97 Edvc97 Awaiting requested review from Edvc97 Edvc97 is a code owner automatically assigned from googleapis/bigquery-dataframe-team
@tswast tswast Awaiting requested review from tswast
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@shuoweil shuoweil

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@shuoweil @tswast @sycai