Google provider docstring improvements

[uranusjr]

Related suggestions found when reviewing #31422.

[uranusjr]

Apparently I broke something but I can’t figure out what’s going on. The error message is quite unhelpful too 😕

[potiuk]

Apparently I broke something but I can’t figure out what’s going on. The error message is quite unhelpful too confused

You can thank sphinx-autoapi for those unhelpful messages, no-one can do much about it.

 WARNING: Definition list ends without a blank line; unexpected unindent.

Apparently the docstring generated rst (in _api folder) contains invalid .rst after your change with missing blank like.

[potiuk]

File path: apache-airflow-providers-google/_api/airflow/providers/google/cloud/hooks/bigquery/index.rst

You can do breeze build-docs --package-filter apache-airflow-providers-google and look at the generated .rst to find out the iseue. Ths is as much as can be done there.

[uranusjr]

I did that, the problem is I can’t even figure out where the generated rst has any issues. The files just look good to me. 🤯

[potiuk]

I did that, the problem is I can’t even figure out where the generated rst has any issues. The files just look good to me. exploding_head

Been there a few times. What worked for me before is doing bisecting and removing parts of the change and figuring out which one is causing it... Not ideal, but works eventually.

And there are hopes we might get some better error messages - I see some activity happening on readthedocs/sphinx_rtd_theme#1463 where people started to complain big time on sphinx_rtd_theme not being updated to Sphinx 7 and THIS PR readthedocs/sphinx_rtd_theme#1464 has just gotten green, so maybe we should also chime in there ?

I think we really need it.

Let me take a look maybe I can figure that one out quickly.

[potiuk]

BTW. breeze build-docs --package-filter apache-airflow-providers-googe --one-pass-only --docs-ony will give you the fastest iteration on this (but the fact that google is about 50% of all provider's code, does not make it exactly fast

[potiuk]

Result of bisecting - you miss empty line here. Also indenting is not consistent with other places but it seem to not cause the problem.

[potiuk]

I checked the bigquery - and the result are missing empty lines before the code-blocks. I leave the other file for you, bisecting might at least tell you what's wrong.

And more complaints and encourgement here will not hurt - I believe Sphinx 7 wil show the right place for the error. Maybe also changing or vendoring the theme and fixing it for Sphinx 7 would be a good option if someone woudl like to take that on.

[potiuk]

Created #31963

[potiuk]

Added comment here as well - readthedocs/sphinx_rtd_theme#1463 (comment) @uranusjr -> I'd appreciate some support/words of encouragement for sphinx_rtd_them developers.

I really feel your pain BTW.

[uranusjr]

FWIW we really should switch away from sphinx-autoapi as well (in favor of sphinx.ext.autodoc), I think that’s another blocker for Sphinx 7 and generally a pain to interact with.

[potiuk]

sphinx.ext.autodoc)

Updated in #31963